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PREFACE 



The MRX/OS Control Program and Data Management 
Services are discussed in two separate documents, each 
designed for a specific type of input/output (I/O) level 
user. This document, the Basic Reference manual, 
contains information at the logical I/O level of processing 
where the blocking and deblocking of data is done for the 
user. The Extended Reference manual is designed for the 
block and physical I/O level user. Block I/O level 
processing recognizes no logical records; therefore, all data 
is read or written as a data block. The physical I/O level of 
processing allows the user to do his own processing of 
data. 

This document provides a detailed discussion of the basic 
MRX/OS facilities provided. Also included is a list of all 
macros and associated keyword parameters needed to 
execute Data Management, Control Program Services, and 
console communication facilities at the logical I/O level. 

Additional and more detailed information may be found 
in the following documents. 

a MRX/OS Control Language Services, Extended 
Reference 

• MRX/OS Control Program and Data Management 
Services, Extended Reference 

• MRX/OS Assembler Reference 
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1. INTRODUCTION 



Through the use of Data Management and Control 
Program Services, the MRX/OS provides the easiest and 
most convenient coding methods for organizing and 
performing input/output (I/O) operations and for direct 
implementation by the system's Control program. 

The system provides the basic user with the following 
facilities at the Assembler language level. 

1. Data Management 

At the logical I/O level of processing, the 
Data Management facility provides sequential 
and random access methods, three file 
organizations (sequential, relative, and 
indexed), device independence, and logical 
record processing with and without a record 
area. 

2. Control Program Services 

Basic Control Program Services available 
include time and date retrieval, and console 
communication. 

3. Debugging 

Debugging capabilities are provided by the 
CHECKOUT routine which allows the pro- 
grammer, through debug request cards in 
the Control Language statements, to call 
for a selection of register and main- 
storage dumps. 
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2. RECORDS, FILES, AND LABELS 



Before considering how processing works within the 
MRX/OS, an idea of what will be processed is necessary. 
This section describes the data in terms of records, files, 
and labels, and Section 3 discusses the data in terms of 
processing. 



RECORDS 

A record can be fixed or variable length and can vary in 
size up to 32K bytes of alphanumeric and/or special 
characters. 



The processing of data files is partially determined by the 
type of file organization. Sequential files can only be 
processed sequentially, while relative files and indexed 
files can be processed both sequentially and randomly. 
Efficiency in processing is provided by the common data 
formats of the file records and labeling of the files. 



Throughout this section, several macros are referenced 
in the discussions of the records, files, and labels. 
Section 6 contains a detailed discussion of each macro 
and its function. 



Table 2-1 gives the legal device usage for file organization, 
record type, and access. 

Table 2-1 . Legal Usage by Device 



>v Device 








Type & ^v 








Usage ^s. 


Unit Record 


Tape 


Disc 


Organization 








Sequential 


YES 


YES 


YES 


Relative 


NO 


NO 


yis; 


Indexed 


NO 


NO 


||§s-* 


Record Type 








Fixed 


YES 


YES 


YES 


Variable 


NO 


YES 


YES 


Access 








Sequential 


YES 


YES 


YES 


Random 


NO 


NO 


YES 



The actual size of a file (determined by the length and 
number of records), file organization, and programming 
requirements are all important to file processing. 
Variable length records can be placed on either sequen- 
tial or relative files; however, the maximum record length 
must be determined and stated in program coding. In- 
dexed files are limited to fixed length records. 



DATA FORMAT 

All data stored by Data Management at the logical I/O 
level on disc or magnetic tape is in a common format, 
except for absolute program images. This format includes 
logical record headers and optional space headers (disc 
files) in each block of data. The common format provides 
the following advantages: 

• Efficiency of processing and decreased mem- 
ory requirements for the GET/PUT level 
blocking and deblocking functions 

• Increased data recoverability by making it 
possible to process logical records (at the 
physical I/O level) without reference to 
associated cataloging or indexing information 

• More complex file organizations or access 
methods for which the record headers will 
contain additional information 

The control information (record headers and space headers) 
is managed by the system for users working at the logical 
I/O level. 
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Records and Record Headers 

A logical record is a contiguous string of user-defined 
data within a block of data. A record header is a 4-byte 
field which precedes each logical record in the block. 
The first byte of the record header is a record identi- 
fier which is unique to that block. The format of a 
record header is as follows: 



RECORD HEADER 



12 567 



I CB | 
J _L 

Byte 



ID 



Byte 1 



RL 



Bytes 2 and 3 



Data 



} 



CB — control byte 

Bits and 1 specify data type. 
01 user data 

10 system data (for example, catalog 
records) 

1 1 user and system data (for example, 
index records) 

Bit 2 specifies last data record for Library 
member only. 

data record in library member 

1 last data record in library 
member 

Bits 3 through 5 are reserved for future 
system use. 

Bits 6 and 7 are always 102 to specify two 
bytes as the length of the record length 
field (bytes 2 and 3 of_the record header). 

I D — record identifier 

RL — logical record length (in bytes) exclusive 
of record header 



Block 



A block is the smallest unit of data which is processed at 
the block I/O level. Files are collections of blocks, all of 
equal length on disc and unit record devices and of 
variable length on magnetic tape. Blocks are made up of 
logical records with record headers and may have unused 
space which is preceded by a space header. In a sequential 
file, records (fixed or variable length) follow in succession 



without space between records; available space is at the 
end of the block. Since indexed files are made up of fixed 
length records only, there is no available space between 
records, In a relative file, however, records may have 
available space between variable length records (blocks are 
formated in increments of the longest variable length 
record) as shown: 



I Ri 



SP 



j R2 



H1 



SH1 



H2 



T 



SP 



X 



SH2 



H1, H2 — record headers 

R1, R2 - logical records 

SH1, SH2 - space headers (optional) 

SP — available space (optional) 

Space headers are 1- to 3-byte fields which describe and 
precede unused space in blocks. The format of a space 
header is as follows: 

012 567 



I CB I 



NBA 



ByteO 



CB — control byte 



Bytes 1 and 2 



Bits and 1 are 00 to specify available 
space rather than data. 

Bits 2 through 5 are reserved for future 
system use. 

Bits 6 and 7 specify the byte length of 
the NBA. 

00 one byte of space available (only 
CB present) 

01 two bytes of space available (CB 
and one byte of NBA containing 
zero) 

10 three bytes or more of space 
available (CB and two bytes of 
NBA containing zero or the 
NBA) 

NBA — number of bytes of space available ex- 
clusive of the header. This field may be ab- 
sent, a single byte containing zero, or two 
bytes containing zero or the NBA. 
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At the logical I/O level, record headers are generated by 
the system when data is stored on disc or tape and are 
removed from the data by the system when stored data is 
retrieved from these media. 



RECORD TYPE 

The data portion of a logical record may be fixed or 
variable length for files residing on magnetic tape or disc. 
Records must be fixed length for files processed from 
unit record devices. 



RECORD SIZE 

Data Management will support (except when maximum 
block length for a particular device imposes lower limits) 
block length between 18 bytes and 32K bytes and 
blocking of logical records up to 256 records per block. 



CONTROL CHARACTERS 

The control characters for the printer and punch are 
included as part of the data record itself, but they are not 
transferred to the output units. (Therefore, if the output 
is to the punch, 81 characters are specified for the record 
size.) The character code defines the operation of the 
carriage control tape of a printer and the stacker selection 
of a card punch. The following lists the ANS control 
character codes and corresponding operations. 



Character 
Code 



Operation 



(blank) Space one line before printing 

Space two lines before printing 
Space three lines before printing 

+ Suppress space before printing 

1 Skip to channel 1 before printing 

2 Skip to channel 2 before printing 

3 Skip to channel 3 before printing 

4 Skip to channel 4 before printing 

5 Skip to channel 5 before printing 



6 Skip to channel 6 before printing 

7 Skip to channel 7 before printing 

8 Skip to channel 8 before printing 

9 Skip to channel 9 before printing 
A Skip to channel 10 before printing 
B Skip to channel 1 1 before printing 
C Skip to channel 12 before printing 
V Select stacker 1 

W Select stacker 2 



The native device control characters are listed in the 
applicable peripheral device reference manual. 

The I/O processing accepts both the ANS character codes 
and native device codes. The CONTROL parameter of the 
OPENL macro specifies which set of characters is being 
used. 

in calculating buffer, record area, and record sizes, the 
appropriate number of bytes must be added for the 
control characters. For example, if the record size is 96 
bytes, another byte is added for the control character; 
thus the record size and record area size is 97 bytes. 
However, only the 96 bytes of data will be printed or 
punched. 



FILES 

A file is a set of records containing related information. 
Such a set of records may be punched into cards (card 
file), printed on forms (printer file), or written on mag- 
netic tape (tape file) or disc (disc file). 

Files are organized in specific manners: sequential, rela- 
tive, and indexed. Files can be classified according to 
their function within the job structure: scratch, temporary, 
work, or permanent. The following paragraphs describe 
the files according to organization and type (classifica- 
tion). 
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FILE ORGANIZATION 

Files assigned to unit record and magnetic tapes are 
always organized as sequential files. 

Random access devices, such as the disc, remove the re- 
strictions of sequential organization and sequential proc- 
essing. Disc flexibility allows for all three types of 
organization and, consequently, the associated methods 
of file processing. 



Relative file organization provides for sequential or 
random creation. The records are placed in a predeter- 
mined order which could be sequential or relative. 
The ACCESS parameter of the DEFRF macro determines 
the processing environment of the file. 



Indexed Files 



Sequential Files 

Sequential files apply to all media: disc storage, magnetic 
tape, and unit record devices. Records are written in 
consecutive locations for sequential file organization. The 
order of the records when the file is created (Figure 2-1) 
determines the sequence for processing the file later. 



When indexed file organization is specified, two types of 
data are generated: the data portion of the file and the 
index portion of the file. 

Allocation of space for the index portion is performed 
automatically when the data file is allocated. The user 
requests allocation through the Control Language 
DEFINE cards and may control placement of both the 
data portion and the index portion to the pack and 
cylinder level if desired (index portion may, therefore, be 
on same pack as data portion or on a separate pack). 



Sequential organization limits processing. Records can 
only be retrieved sequentially beginning with the first 
record of the file and subsequently retrieving each 
record in the file. Any changes, additions, or deletions 
to a magnetic tape or card file involves recopying the 
entire file. The additions are included in the file and the 
deletions are excluded. For a sequentially organized 
disc file, changes can be made to individual records 
without retrieving unchanged records, providing no 
additions or deletions exist. 



The number of blocks needed for the index portion is 
calculated by the allocation routine from the number of 
data blocks estimated, the key length, and the number of 
keys per block specified. 

Appendix D gives the layout of the index portion of the 
file. 



Relative Files 

The position of logical records in a relative file is given 
by a record number relative to the beginning of the file. 
The GET/PUT logic changes this record number into 
a block number and a relative position (record identi- 
fication) within that block. 

The records are written into preformated blocks on the 
basis of the block record number (Figure 2-2). 
Preformating is accomplished at file creation time by the 
OPENL macro. Blocks are ■ preformated over the entire 
allocated space in the common stored data format with 
binary zeros in the logical record area. Record deletion or 
further maintenance of blank records is a user 
responsibility. 



Data Portion of Indexed File 

The data portion of an indexed file is written into blocks 
that have been preformated by the OPENL macro at disc 
file creation. As successive blocks are written, they are 
scattered around each disc track so that a fixed number of 
blocks may separate two logically consecutive blocks on a 
track. The number of blocks separating logically 
consecutive blocks can vary from to 9. Scattering is 
done to increase the probability that two successive data 
block readings can be performed without losing a disc 
revolution. The number of blocks which separate logically 
consecutive blocks is determined by a spread factor 
established as a file attribute through the allocation 
process. 
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CARDFILE 



f 



r 



( 



r 



RECORD 1 



RECORD 2 



RECORD 1 



RECORD 3 



RECORD 4 



RECORD 2 



RECORDS 



RECORD 5 



RECORD 4 



RECORD 5 



I 1 

I Records are placed in j 
j consecutive locations | 



on the disc. 



DISC FILE 



V 



Figure 2-1. Sequential File Organization 



CARDFILE 



RELATIVE RECORD 
NUMBERS 



*3 



6 



RECORD B 



RECORD C 



RECORD A 



RECORD D 



RECORD A 



'/////////////Z,,, 

///// EMPTY W///A RECORD D 



RECORD B 



! 

| Records are positioned 
j according to relative record 
I number. 



RECORD C 



j DISC FILE 



5 RECORD POSITION 



Figure 2-2. Relative File Organization 
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CARDFILE 



r 



r 



f 



c 



RECORD 1 



I 



RECORD 2 



RECORD 3 



RECORD 1 



RECORD 2 



RECORD 4 



RECORD 5 



RECORDS 



RECORD 4 



RECORDS 



3 



DISC FILE 



While the data tile is 
being built, the indexes 
are also being created. 



DIRECTORY TO THE 
DIRECTORY INDEX 



Key value and its 
associated directory 
index block number 



^ 



DIRECTORY INDEX 



Block 1 



Key value and its 
associated primary 
index block number 



^ 



PRIMARY INDEX 



Block 1 



Key value and its 
associated block 
record address 



Block r 



Block n 



The directory to thB directory index, 
which is located on disc, and may be 
processed on disc or in main storage, 
gives the first value in each directory 
block. The directory index gives the 
first value in each primary index 
block. The primary index, in turn, 
gives the associated block record 
address for a key value. Entries in 
the directories are assembled in 
ascending order according to the 
keys. 



Figure 2-3. Indexed File Organization 
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Index Portion of Indexed File 

The locations of logical records in data files are recorded 
in an index portion of the file by means of a three-level 
table look-up indexing scheme (Figure 2-3). Each record 
has a unique primary index key value, which is recorded 
with the block record number in the primary level index 
block at file creation time. A directory level index, which 
locates the primary index blocks for random access, is also 
generated at file creation time. Another index, a directory 
to the directory level index is also generated. This 
additional directory is read into main storage (if specified 
by the INMAIN parameter of the DEFIF macro) at the 
opening of the file, thus increasing the efficiency of 
random retrieval. 

Random access is performed by reading the directory to 
the directory index and the directory blocks, followed by 
an access to the appropriate primary index block. The 
data is then accessed by the block record number found in 
the primary index block. 

Sequential access is performed by main-storage processing 
of primary index blocks. A look-ahead process for a 
change in block number within each index block provides 
the overlap of data block transfer with logical record 
processing. A linkage chain among primary index blocks is 
used to handle overflow of the primary index blocks. 

Creation of indexed files requires that the data be 
presented in the ascending order of the collating sequence 
of the primary key values. As data blocks are created, the 
index information is generated by the GET/PUT modules 
for indexed files and written in the index blocks. A ten 
percent margin remains in each index and directory block 
to accommodate the addition of data records. 

Indexed files may be extended by addition of more data 
records, presorted in the sequence of the primary index 
key values, if the key value of the first data record of the 
extension is greater than the highest key value processed 
during creation. This extension is performed by specifying 
output usage in the OPENL macro. The positioning to the 
end of current information and initializing tables is 
performed by the OPENL macro. No previous updates are 
allowed if the file is to be extended. 



moved into this new block to minimize the chance of 
further overflow in the same area. 

When data is deleted, the index information for the 
deleted record is removed, but the data record is not 
modified. 

FILE TYPE 

Each file has a disposition type (scratch, temporary, 
work, or permanent) established when space is alloca- 
ted for the file. 



Scratch 

Scratch files are used by jobs that have several job steps. 
These files exist only for the duration of a job step and, at 
the end of the job step, are purged by system control. The 
file is positioned at the beginning of the file by the 
OPENL macro. Scratch files cannot have an indexed file 
organization. 



Temporary 

Temporary files provide a temporary storage area for job 
processing. They exist only for the duration of the job 
and, at the end of the job, are purged by system control. 
The file is positioned at the beginning of the file by the 
OPENL macro. Temporary files cannot have an indexed 
file organization. 



Work 

Work files occupy permanently allocated space; how- 
ever, the file data exists only for the duration of a job. 
If a work file is opened for output use, the pointer for 
placement of the data is positioned to the beginning 
of the file. Work files must have sequential file organi- 
zation. 



Data may be added, deleted, or updated either randomly 
or sequentially by opening for update usage. When data 
records are added they are written after the current last 
record in the data portion of the file. A record address is 
then inserted into the appropriate primary index block. If 
additions of many records in the same region of primary 
index causes the primary index block to overflow, a new 
block is linked into the first level linkage chain and some 
of the record addresses in the block which overflowed are 



Permanent 

Permanent files occupy permanently allocated space and 
the file data is permanent. If a permanent sequential file is 
opened for output use, the data is added to the end of the 
file. For relatively organized files, the records are added 
wherever specified. For indexed files data is added to the 
end and must be presented in the collating sequence of 
the primary key beginning above the current high key 
value. 
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SUMMARY OF FILE TYPES BY ORGANIZATION 



LABELS AND CATALOGS 



Table 2-2 provides an easy reference to the file types 
allowed for each file organization. It notes how records 
are added to permanent files. 



Table 2-2. File Types By Organization 



\ File 








^v. Organization 








File ^s. 








Type \. 


Sequential 


Relative 


Indexed 


Scratch 


Legal 


Legal 


Illegal 


Temporary 


Legal 


Legal 


Illegal 


Work 


Legal 


Illegal 


Illegal 




Legal 


Legal 


Legal 


Permanent 










Records 


Records 


Records 




are 


are 


are added 




added to 


added 


to the end 




the end 


wherever 


of file 




of file 


user 
specifies 





File labels ensure the opening of a correct file for a 
particular job. The OPENL macro checks the file for 
the proper name and attributes. Since Data Management 
handles labels and catalogs, the basic user need not 
be concerned with the physical aspects of label and 
catalog checking (the Control Program and Data 
Management Services, Extended Reference manual pro- 
vides this information). 



TAPE LABELS 

Tape labels are special records at the beginning and end of 
magnetic tape files (Figure 2-4). They are used to identi- 
fy the reel of tape and the succeeding file, as well 
as certain information for file maintenance. All labels 
may not have the same format. Some tapes may be un- 
labeled and others may have user-supplied nonstandard 
label formats. 



LABELED 
TAPES 



^ 



LOAD POINT 



VOLUME 
LABEL 



HEADER 
LABEL 1 



HEADER 
LABEL 2 



DATA RECORDS 



TRAILER LABEL 



X 



LOAD POINT 

OPTIONAL TAPE MARK 
» ▼ 



UNLABELED 
TAPES 



V 



DATA RECORDS 



X 



NONSTANDARD 
TAPE LABELS 



'V 



LOAD POINT 



LABEL 



DATA RECORDS 



X 



Figure 2-4. Tape Organization 
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Standard Tape Volume Label 



The volume label is located at the beginning of a tape reel 
and is identified by the characters, VOL, found in the first 
three positions (Figure 2-5). The volume label number is 
always 1 for compatibility with IBM. The volume serial 
number occupies positions 4 through 9 and identifies the 
volume. A unique owner name and address code identifies 
the installation. 



BYTE D 
1 
2 


VOL 


3 


VOLUME LABEL NUMBER 


4 




VOLUME SERIAL NUMBER 




9 








10 














«* 


40 




'i|l'lssr25f™Si : ir 




41 
SO 


OWNER NAME 

AND 

ADDRESS CODE 




51 









-EQUALS 1 




Figure 2-5. Standard Tape Volume Label 



Standard Tape File Label 



BYTE 
1 
2 
3 

4 



47 



LABEL IDENTIFICATION 



FILE LABEL NUMBER 



FILENAME 



FILE SERIAL NUMBER 



VOLUME SEQUENCE NUMBER 



CREATION DATE 



EXPIRATION DATE 






BLOCK COUNT 



79 



HDR 
EOF 
EOV 



The standard tape file label provides information 
concerning the user's file such as creation and expiration 
dates, file name, and sequence number (Figure 2-6). The 
label identification field identifies the type of standard 
label with a three letter abbreviation. Three types of labels 
supported by the system are header labels (HDR), 
end-of-file labels (EOF), and end-of-volume labels (EOV). 
The file label number found in byte 3 is 1 or 2. The file 
serial number, found in positions 21-26, is identical to the 
volume serial number in the volume label of the first 
volume. The volume sequence number identifies the order 
of the volume of data records in a multivolume logical 
file. The block count provides the number of physical 
records written in a file at creation. 



Figure 2-6. Standard Tape File Label 
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DISC LABELS 



DISC STORAGE CATALOGS 



Disc packs have a standard volume label containing 
volume identification and owner information (Figure 2-7). 
The device type, owner, and state of the volume — 
unrestricted (0), restricted (1), or locked (2) - are 
included along with the starting track address of the pack 
catalog for this volume. The actual file identification is 
found in the disc catalogs. 



The space management routines (explained in the 
Control Program and Data Management Services, Extended 
Reference manual), in performing their function, main- 
tain the central catalog and pack catalogs on disc. 
The central catalog, existing once for a system, contains 
an entry for each file cataloged in the system. The 
entry identifies the file and describes the volume(s) 
occupied by the file. 



byte o 



VOL 



VOLUME IDENTIFIER 



STATE OF VOLUME 



POINTER TO VTOC (VOLUME 

TABLE OF CONTENTS) ONLY ON 

CONVERTED IBM PACKS 



OEVICE TYPE 



PACK CATALOG ADDRESS 



The pack catalog, existing on each volume, contains an 
entry for each file occupying space on the volume. 
The entry identifies the file and describes the space 
occupied by the file. 




Figure 2-7. Disc Label 



Disc files are described by file labels found in the pack 
catalogs, which are resident on each disc pack in the 
system. The file labels contain the file name, file 
attributes, and a physical description of the segments of 
disc space allocated to the file on this pack. The actual 
fields of the catalogs can be found in the Control Program 
and Data Management Services, Extended Reference 
manual. 
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3. I/O PROCESSING 



The I/O processing capabilities of MRX/OS are divided 
into three levels: logical, block, and physical. The logical 
I/O processing level, discussed in this section, blocks and 
deblocks data for the user; block I/O processing 
recognizes no logical records (data is read or written as a 
data block); physical I/O allows the user to do his own 
I/O processing. The block and physical I/O processing 
levels are discussed in detail in the Control Program and 
Data Management Services, Extended Reference manual. 

The logical I/O level Data Management functions are 
provided by relocatable subroutines which are loaded with 
and linked to the user programs which request them. They 
require MRX/OS control program, system control, loader, 
and library functions. 



ACCESS METHODS 

Two access methods are provided at the logical I/O level, 
sequential and random. 



SEQUENTIAL ACCESS 

Sequential access is a method of retrieving records 
consecutively in the order of logical arrangement in the 
file. All file organizations are sequentially accessible. 

Sequential access is the only method that can be used for 
retrieving sequentially organized file records. Relatively 
organized file records can be processed sequentially by 
beginning at the start of the file and processing each 
successive record. Indexed file records also can be 
processed sequentially by retrieving in the sequence of the 
primary key values. By using the SETL macro, all the 
records in an indexed file may be retrieved starting at the 
beginning of file, or a portion of the file may be retrieved 
by selecting a key value for the beginning of the 
processing. The SETL macro, however, is not necessary to 
start processing at the beginning of an indexed file; Data 
Management will process from the beginning unless 
otherwise specified. 

Figure 3-1 illustrates the sequential access method. 
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Sequential File 
or 
Relative File 



I 2 3 4 5 6 7 B 



F.I. LEI 
Ml. LCI 



OPERATION 



' II 1? 13 10 IS 16 17 



D£FSF 
DE.FRF 



GST. 



19 20 21 2223 ;-W5 ?K 27 Z8 21 30. 31 32 33 34 35.36 3) 3B 39 40 41 ,42, 43 44 15 46 47 48 49 50 51 52 53 54 55 55 57 58 59 f 



... .. ...._. ..uflr _....._, ^ _ . x _^ . . . tJ . _, 

A<LC£SS*S^Al&SJ,Z~M^ Mcs.IZ s.~9A ...:. . 

&ECTX.to.£ ._. ! !!_, * _ 



i.6.EMf'F;i£ii > tew ; 



FILE 1 



^ 



RECORD 1 



RECORD 2 



RECORD 3 



h 



I 1 

| Retrieves first record and each | 
| succeeding record. j 

I I 



INDEXED FILE 



From beginning 
of file 



12 3 4 5 6 7 



t.lLEl 



FILE 2 



D.£F.lF 



10 11 12 13 14 15 18 17 



SELL. 
SET. . 



\ 



RECORD t 



19 20, 21 22 23 24 35. 2G 27 28 29 30.31 32_ 3:> 34 35, 36 37 3S 39 40 41 42 43 44/15 4547 48 49 50,51 52 53 54 55,56 57 E 



i j nu iwiuiywi^ ;b ;j ju ji j/ j, > ja is Jo j; jb jy io 41 4? 43 44 15 46 4/ 48 49 50 51 52 53 54 

Rec.fi i.z.*.9a,.j Ki.sj .z=,so+,K,ex.!ujL^3, _„ 

'.Ajf.i<.-.Hf.s.,../.xi£;v.r.fA^4>,aj.<r^Aei?jsj J r...^r. 



RECORD 2 



RECORD 3 



i 



Retrieves first record and each 
succeeding record. Allocated 
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> ! Allocated with a spread factor of 



Figure 3-1. Sequential Accass Method 
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RANDOM ACCESS 

Random access is a method of retrieving individual 
records from a file. Only relative and indexed file 
records are randomly accessible. 

F : or relative files, the record number of the desired 
record is changed into a block number and a relative 
position within that block. From this computed infor- 
mation the record is directly accessible. 

For indexed files, the key values specified as the actual 
keys indicate the desired records. A search in the direc- 
tory to the directory index block, the directory index 
block, and the primary index block gives the appropriate 
block record number of the desired record. The data 
record is then retrieved by the block record number. 

Figure 3-2 illustrates the random access method. 



LOGICAL RECORD PROCESSING 

Blocking/deblocking of logical records is provided by 
GET/PUT macros, which move logical records between a 
record area and an I/O buffer or which process records 
in an I/O buffer. Processing may be either sequential 
or random with a record area and one or two I/O buffers 
defined. 



Buffer switching increases efficiency of processing because 
reading and processing operations occur simultaneously 
with no waiting involved. 



FILE SHARING 

OPENL checks shared files on volumes which are 
mounted on shared resources. Output usage ensures 
exclusive use of the file. Update usage ensures that no 
other program can update the file until it is closed, but 
other programs may have access to the file. Table 3-1 
indicates the legality of usage when program 1 opened the 
file and an OPENL macro from program 2 is checking for 
usage conflicts. 

Table 3-1 . Usage Conflicts 



^\^ Program 1 
^s. Usage 

Program 2 ^s. 
Usage ^s. 


Input 


Update 


Output 


Legal 


Input 
Update 


Input 


None 


Illegal 


Output 


Update 
Output 


Input 

Update 

Output 



BUFFER SHARING 



BUFFER SWITCHING 

If two buffers are specified, a buffer switching process 
is performed. For a GET request, as the records are 
transferred from the second buffer, the next data block 
is simultaneously transferred into the first buffer. 
Figure 3-3 illustrates the buffer switching involved for a 
GET request. 

Buffer switching for PUT is similar to GET but in reverse 
order. Records which have been processed in the record 
area are transferred to the appropriate I/O buffer. As soon 
as the last record* has been transferred to buffer 1, the 
next record is transferred to buffer 2, and simultaneously 
buffer 1 has its records put on the output data file in 
the appropriate block. Figure 3-4 illustrates buffer 
switching for PUT requests. 



* For variable length records, this is the last whole record the 
buffer can contain. 



When buffer sharing has been specified in the define 
macro, an additional two bytes must be added to the 
buffer size. This 2-byte field is used by OPENL and 
CLOSEL to resolve buffer usage conflicts. 



SEQUENTIAL PROCESSING WITH RECORD AREA 

The GET macro transfers a block of input data into an I/O 
buffer. From the I/O buffer, the logical record goes to a 
record area. When the last logical record in a data block 
has moved to a record area, the buffer is refilled. If a 
second I/O buffer is specified, buffer switching is per- 
formed; control returns to the user when the buffer 
switching is completed. Figure 3-5 illustrates the GET re- 
quest using both a record area and a buffer. 

The PUT macro moves a logical record from a record area 
into an I/O buffer. Buffers are emptied after the last 
record has been put into the current I/O buffer or when 
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Figure 3-2. Random Access Method 
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INPUT 
DATA 
FILE 



\: 



BLOCK 1 



BLOCK 2 



BLOCK3 



BL0CK4 



7 



When two buffers are 
specified, G ET trans- 
fers data blocks to each 
of the buffers. 



BUFFER 1 



RECORD 1 


RECORD 2 


RECORD 3 



BUFFER 2 




RECORD 4 


RECORD 5 


RECORDS 



1 Processed Data 



| " 1 

As soon as GET transfers the last record 
found in Buffer 1 and starts transferring 
• records from Buffer 2, Block 3 is trans- 
I ferred into Buffer 1. The reading and 
processing of data blocks occur simul- 
taneously. 



Figure 3-3. Buffer Switching with GET Request 




RECORD AREA 



BUFFER! 



RECORD 1 


RECORD 2 


REC0RD3 



BUFFER 2 



Processing of input data record occurs 
in the record area. As soon as PUT 
transfers the last record in Buffer 1 
and starts transferring records into 
Buffer 2, the records in Buffer 1 are 
put on the output data file in the 
appropriate data block. 



RECORD 4 



RECORD 5 



RECORD 6 



OUTPUT \ 
DATA \ 
FILE V 



BLOCK 1 



BL0CK2 



BLOCK 3 



BLOCK 4 



7 



Figure 3-4. Buffer Switching with PUT Request 



3-5 



INPUT 
DATA 
FILE 



Y 



BLOCK 1 



BLOCK 2 



BLOCK 3 



BLOCK 4 



i 



GET retrieves a block of input 
data and places it in a buffer. 



BUFFER I RECORD 1 



RECORD 2 RECORD 3 RECORD 4 



RECORD AREA I RECORD n 




! Processed Data J 



Each record from the buffer is transferred 
individually to the record area until the 
buffer is empty. 



{ Processing of the record occurs in the record area. 
I 

I . _.__ 



Figure »5. GET Request with Record Area 



r- 1 

I Input Data I 
I , 1 



RECORD AREA 



RECORD n 



Processing of the input data record occurs in the record 
Brea. 



BUFFER 



RECORD 1 


RECORD 2 


RECORD 3 


RECORD 4 



■ Each record is transferred individually to 
the buffer until it is filled. 



OUTPUT 

DATA 

FILE 



\ 



BLOCK 1 



BLOCK 2 



BLOCK 3 



BL0CK4 



\l Whenth 
I of date i 



the buffer is full, the block 
is put on the output file. 



Figure 3-6. PUT Request with Record Area 
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INPUT T^ 

DATA \ 
FILE V 



BLOCK 1 



BLOCK 2 



BLOCK 3 



BL0CK4 



1 



GET retrieves a block of 
input data and places it in 
a buffer. 



BUFFER I RECORD 1 



RECORD 2 



RECORDS 



R1 



Address of available record area 



Processing of the record occurs in the buffer. 
R1 contains the address of the next logical 
record to be processed. 



j— — — — | 

| Processed Data | 

I I 



Figure 37. GET Request Without Record Area 



BUFFER 



j Processing of the record occurs in the buffer. 
j R1 contains the address of the area of the 
j buffer available for the next logical record. 

I 




f . .__ , 

| After the buffer is full, the block | 
j of data is put on the output file. f 

I I 



Figure 3-8. PUT Request Without Record Area 
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the space left in the current I/O buffer will not contain 
the next variable length record. If a second I/O buffer 
is specified, buffer switching is performed before re- 
turning control to the user; if a second I/O buffer is not 
specified with variable length records, the next variable 
length record is not moved into the buffer until it has 
been emptied. Figure 3-6 illustrates the PUT request 
using both a record area and a buffer. 



SEQUENTIAL PROCESSING WITHOUT A RECORD 
AREA 

GET returns to the user, in genera I -purpose register 1 
(R1), the address of the first data character of a logical 
record in the buffer which is available for processing. 
Buffers are refilled after the GET request for the first 
logical record of a block is made. If a second I/O buffer is 
specified, buffer switching is performed; control returns 
to the user upon switching completion. If there is only 
one I/O buffer specified, control is retained by Data 
Management until the buffer has been filled. Figure 3-7 
illustrates the GET request using only an I/O buffer for 
processing. 

PUT returns to the user, in R1, the first character address 
in the buffer which is available for the next logical record. 
Buffers are emptied after the PUT for the first logical 
record in the block is made. If a second I/O buffer is 
specified, buffer switching is performed; control returns 
to the user upon switching completion. If there is only 
one I/O buffer, control is retained by Data Management 
until the buffer has been emptied. Figure 3-8 illustrates 
the PUT request using only an I/O buffer for processing. 



RANDOM PROCESSING 

While in the random mode of processing, GET retrieves 
a specified record. The buffer is filled if the specified 
record is not currently in the I/O buffer. If a second I/O 
buffer is specified, it is not used. 



When a record area is used, the GET request moves the 
requested record through the I/O buffer to the record 
area; however, if only a buffer is available, the first 
character address of the record in the I/O buffer is 
returned to the user in R1. Figure 3-9 illustrates the 
processing of a randomly retrieved record with and with- 
out a record area. 



When a record area has been specified, the PUT macro 
empties the buffer if it contains an updated record but 
does not contain the specified record. The buffer is then 
filled with the data block that is to contain the new 
record; the record is moved into the buffer. If this is 
an update process, the data block of this particular 
record must be in the buffer before PUT transfers the 
record. (Thus a GET request is issued first.) 

While in random mode, PUT macros are processed only 
when a record area has been specified. Figure 3-10 
illustrates the processing of the PUT macro while in 
random mode. 



MAGNETIC TAPE PROCESSING 

MRX/OS supports three types of labels: 

• Standard labeled tape 

• Nonstandard labeled tape 

• Unlabeled tape 

The default for no LABEL specification is standard labels. 
The nonstandard option is valid only for input files. 



The label type may be selected at assembly-time through 
the optional LABTYP parameter of the DEFSF macro or 
at run-time through the LABEL parameter of the 
//DEFINE statement. However, the LABEL parameter of 
the //DEFINE statement overrides any label specification 
in the BDT which is created by the DEFSF macro. 



On the //DEFINE card, the Control Language specifies 
the type of magnetic tape labels, plus two additional 
features - ignore and bypass label processing. The LABEL 
keyword parameter has the following format: 
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GET REQUEST WITH RECORD AREA 



INPUT 
DATA 
FILE 



\ 



BLOCK1 



T 



BLOCK 2 
RECORD 1 I RECORD 2 



BLOCK 3 



\ 



BUFFER 


1 RECORD 1 


RECORD 2 




, \ 


RECORD AREA 


1 

I Specified Record 




i 


' 




r -| 

I Processed Record | 



GET transfers the data block containing the 
specified record to thB I/O buffer. This record 
is then placed in the record area for processing. 



GET REQUEST WITHOUT RECORD AREA 



INPUT \ 

DATA \ 

FILE \ 



BUFFER 



BLOCK 1 



BLOCK 2 
RECORD 1 I RECORD 2 



BLOCK 3 



i 




I — *- — l 

| Processed Record I 



GET retrieves the data block and 
places it in the I/O buffer. R1 
gives the first character address 
of the specified record in the I/O 
buffer. 



Figure 3-9. Random Access with GET Macro 
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PUT REQUEST WITH RECORD AREA 



1 Input Record I 
I ,_ I 



RECORD AREA 



RECORD n 



PUT processes the record in the record area 
and transfers it to the buffer. If this is an 
updated record, the buffer has the data block 
of this record and the record is rewritten. 
The data block is written on the output date 
file only when the block (still in the buffer) 
containing the new or updated record can- 
not receive another record in that particu- 
lar block. 



BUFFER 



RECORD 1 



RECORD 2 I 
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DATA 

FILE 



\ 



BLOCK 1 



BLOCK 2 



BLOCK 3 
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X 



Figure 3-10. Random Access witti PUT Macro 
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The codes are defined as: 



Code 


Definition 


S 


Standard tape labels 


N 


Nonstandard tape labels 


U 


Unlabeled tapes 


B 


Bypass label processing 


1 


Ignore label processing 



Chapter 2 of this manual describes the format of standard 
labels, nonstandard labels and no labels. 

OPEN TAPE FILE 

Each OPEN(L) request for a tape unit must be supported 
by a //DEFINE Control Language statement. The SYSIN 
(system input file) is searched using the I DENT field 
supplied by the OPEN macro. If no match is found, an 
error is returned. 

Tape units are assigned forexclusive use of a job-step by 
the Step Initiator. OPEN(L) issues a mount reel request, if 
necessary, for each unit (1 or 2 per IDENT) assigned by 
the Step Initiator.* The message includes volume 
identification, reel sequence number and unit number. If 
REWIND=NO is specified in the OPEN(L) macro, no 
rewind is performed before checking labels. 

After label checking, an FDT (File Description Table) is 
built and linked into the FDT string. If the file is open for 
logical I/O processing, buffers are prefilled, and control 
returns to the caller. 

Bypass and Ignore Tape Labels 

The bypass and ignore options of the LABEL parameter 
are valid for input files only. If ignore (I) is selected, no 
tape positioning or label checking occurs. If bypass (B) is 
selected, no label checking between existing label and the 
Control Language options occurs. 

When the bypass option is used, the first tape record is 
read. If it is a tape mark, the tape is an unlabeled one and 
is positioned at the first data record and no further 
positioning occurs. If the first record is a standard tape 
volume label, it is a standard labeled tape and a forward 
space file routine positions the tape to the first record 
beyond the label set. If the first record was neither a tape 
mark nor a standard tape volume label, an unlabeled tape 



•Step Initiator is a module of Control Language Services. 



is assumed and a backspace record routine positions the 
tape to the beginning. The user is then responsible for 
correct positioning of the tape with nonstandard labels. 

Input files must conform to the label requirements; this 
allows no operator override. If a conflict exists, a rewind 
request is issued and the operator must mount the correct 
tape reel. 



Standard Tape Labels 

When the input file has standard labels, the volume serial 
number of the tape volume label must match the 
VOLUME parameter of the //DEFINE statement; and the 
filename of the first header label (standard tape file label) 
must match the FILENAME parameter of the //DEFINE 
statement. A forward space file routine then positions the 
first data record. If the filename in the header does not 
match the FILENAME parameter, the operator receives a 
message to retry or abort. 

When the standard labels option is selected for an output 
file, standard labels both volume and header labels must 
be written on the tape. If the volume label does not exist 
on the tape, a message is issued to the operator who must 
respond with RETRY or the information necessary to 
create a standard volume label. A standard tape file label 
(HDR1) is created from the Control Language 
information. A second header label (HDR2) is written 
with all fields of zero and followed by a tape mark. If the 
standard volume label does exist, the first header label is 
read. If HDR1 is valid, the expiration date is checked. For 
unexpired files, a message is issued; and the operator 
responds with RETRY or ACCEPT. RETRY starts the 
sequence again and ACCEPT allows the volume to be used 
as if expired. 

Nonstandard Tape Labels 

The nonstandard label option is only valid for input files. 
A read of the first record on the tape is issued. If the 
record is not a standard volume label, a forward space file 
positions the type beyond the header label set. 

Unlabeled Tapes 

The first record of an unlabeled input file is read. If it is a 
tape mark, the first data record is in position. If it is not a 
tape mark, a backspace record routine positions the first 
data record. 

For output files, the first record is read. If the record is a 
standard volume label, the next record is read. If the next 
record is not a HDR1 label, the file is backspaced and a 
tape mark is written. If the second record is a HDR1 label, 
the expiration date is checked. If the file is expired, the 
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file is backspaced and a tape mark written; a message 
informs the operator that a standard volume label is being 
overwritten. If HDR1 is not expired, a message is issued, 
and the operator may ACCEPT or RETRY. If the record 
is a tape mark, the correct record is in position. If the first 
record is not a tape mark nor a volume label, the tape is 
backspaced and a tape mark written. 



Input Files Without Standard Labels 

While processing input files with the ignore, bypass, 
nonstandard, or unlabeled option, the operator must 
indicate if there are more volumes to the tape file. If this 
is the last input volume, EOF is set in the CLOVE packet, 
and control returns to the caller. If it is not the last 
volume, label processing for this volume is the same as in 
CLOSE. A REWIND=UNLOAD and a request to mount 
the next volume are issued. Label checking for the next 
volume follows the OPEN procedure. 



CLOSE TAPE FILE 



At the end of processing a tape file certain steps are taken 
according to the option selected. 

After any label processing is done, a rewind/unload is 
issued unless a CLOSE(L) with REWIND=NO was 
specified. The FDT is taken out of the FDT string unless 
CLOSE(L) with LOCK=YES was specified. Control is 
then returned to the caller. 



Output Files With No Labels 

After processing an unlabeled output tape, two tape 
marks are written and a mount the next volume is 
requested. Label processing occurs for the next volume as 
in the open routine. 



Ignore and Bypass Tape Labels 



Files with Standard Labels 



When the ignore or bypass option is selected, no trailer 
label checking is performed. 



Standard Labels 



When the files have standard labels, the current volume 
processing is the same as CLOSE except the last record is 
an EOV instead of EOF. A mount message is issued for 
the next volume, and the processing continues as in 
OPEN. 



When processing an input file with standard labels, the last 
record (which should be an EOF record) is read. If it is 
not an EOF and the FDT indicates the end of file, a 
message is issued to the operator, and no comparison of 
block count (FDT vs. trailer label) is made. If the record is 
an EOF, the trailer label block count is compared with the 
block count for the volume; a console message indicates 
an error when the two block counts are unequal. 



After label checking is complete, the FDT is updated if 
necessary and control returns to the caller. 



IBM TAPE PROCESSING 



After writing the last data record in an output file, a tape 
mark, an EOF trailer label with block count, and two tape 
marks are written. 

Nonstandard Labels and Unlabeled Tapes 

When processing input file with either nonstandard tape 
labels or no tape labels, no label checking occurs. After 
completion of writing an unlabeled output file, two tape 
marks are written. 



A mode of processing which does not use the common 
stored data format (described in Chapter 2) will be 
available for processing of IBM format F and U magnetic 
tapes. This mode is selected on tape by specifying 
CSD=NO in the //DEFINE statement and by specifying 
BLKFAC=n for format F and BLKFAC=1 for format U in 
the DEFSF macro. 



VOLUME SWITCHING 

The CLOVE(L) macro performs volume switching for 
multivolume tape files. CLOVE(L) performs header and 
trailer label processing on tapes and alternate unit 
processing on tapes. 
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INTERACTION OF DATA MANAGEMENT AND 
MRX/OS CONTROL LANGUAGE 

The Control Language Services, through the //DEFINE 
statement of the Control Language, provides a run-time 
interface with some of the Data Management services. 
Rather than coding into the program all the attributes 
of each file to be processed, the user supplies certain 
information about the files in the //DEFINE statement. 
In this way changes, which might otherwise require re- 
assembly of the program, only require modification of 
the Control Language statement. Thus, the program tends 
to remain independent of such things as the name of the 
file being processed, what device or volume the file re- 
sides on, and for sequential files the type of media 
used for processing. The Control Language Services 
provides the additional service of requesting allocation 
of space for new disc files from the user supplied param- 
eters. 

For sequential files, the Control Language can change the 
file to any device. If files have the same characteristics, 
the file name specified in DEFLB and referenced by the 
OPENL macro can be overridden by the Control Language 
with different file names; that is, files other than the one 
specified by OPENL can be processed. 

At the logical I/O level, the Control Language can handle 
all the space management (allocation, expansion, and 
purging). After a control table has been set up by the 
Control Language, Data Management can use these 
parameters for OPENL/CLOVEL routines. 

When a file is opened (OPENL macro), a File Description 
Table (FDT) is established. The file attributes described 
in the table are taken from the System Control Table 
(SCT) established by the //DEFINE statement and the 
Buffer Description Table (BDT) established by the define 
macros. (The Control Language Services, Extended Refer- 
ence manual provides a detailed discussion of the at- 
tributes specified by the //DEFINE statement.) 

The CLOVEL macro uses thevolume information to switch 
volumes. The file name of this macro overrides DEFLB 
macro information. 



Example 
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The file attributes for FILE4 (cataloged as FILE4PAY) 
are as follows: 

Record size of 1 00 
Block size of 1 04 
Two buffers 
Estimated 1 000 records 
Permanent disc file 
Input file 

Volume-id 104000 

Common stored data format 
Sequential organization 
Cataloged file 
Error routine 
Record area 

The OPENL macro places the file attributes in the FDT. 
The Control Program and Data Management, Extended 
Reference manual contains an exact layout of the FDT. 
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4. CONTROL PROGRAM SERVICES 



All service requests are initially interpreted by the Control 
Program, but most of them are then transferred to 
separate routines for processing. There are, however, 
certain service requests which are processed directly by 
the Control Program. The two services that fall into this 
category are program termination and time and date 
retrieval. 

PROGRAM TERMINATION 

The program termination macro is necessary for returning 
control to the system in an orderly fashion on completion 
of a program. Three Control Program Service macros, 
HALT, EHALT, and ABEND are provided for this 
purpose. 

These macros differ primarily in their effect upon 
subsequent steps of the job. HALT (required in all 
programs) will not affect subsequent steps in any way. 
EHALT (error halt) and ABEND (abnormal end) will 
cause any subsequent job steps to be bypassed, going 
directly to the end of job. 

In addition, ABEND provides the ability to log a discrete 
binary completion code in the Job Control Table which is 
displayed on SYSOUT. ABEND also forces a dump of the 
partition, unless a DUMP=NO was coded on the 
//EXECUTE statement. 

The DUMP= keyword operand, when coded explicitly in 
the //EXECUTE statement, will cause the partition to be 
dumped or not dumped as specified, without regard to 
whether termination was via HALT or EHALT. If the 
DUMP option was not coded on the //EXECUTE 
statement, termination via HALT or EHALT will not 
cause a dump; but termination via ABEND will cause the 
partition to be dumped. 

Neither the HALT macro nor the EHALT macro requires 
any operands. ABEND requires a specification of 
completion code desired to be logged. 

Programs may also be terminated by giving control to an 
exit routine located in the system linkage area. For this 
method to work properly, the user program must not 
disturb (or must save and reload) the contents of general 
register 7 since this will be loaded by the system with the 



exit linkage address. To terminate the program a BR @7 
should be coded in place of the HALT. This method of 
termination allows the program to serve as a subroutine 
which either links back to the caller or terminates 
depending on the contents of register 7. (Appendix B 
describes the linkage conventions.) 

TIME AND DATE RETRIEVAL 

The operating system maintains the current time and date 
for access by user programs. A user program may read 
the current time and date by means of the TIME and 
SDATE macros which will return the time or date to 
a user specified storage location. Neither the time nor the 
system date may be altered by a user program (only by 
operator command), but there is a second date area 
in the system which is available for storing a date asso- 
ciated with a particular job. The user may set this job 
date to any date he wishes by means of a //SET state- 
ment in the Control Language for his job. To read the 
job date within the program the JDATE macro must be 
used. If the job date is not set in the Control Language 
statements, the system date will be used, and any JDATE 
macros in the program will then receive the system date. 

The use of TIME, SDATE, and JDATE involves specifying 
a location where the time or date is to be received. TIME 
gives the time of day in hours, minutes, and seconds while 
SDATE and JDATE have the option of calendar or Julian 
formats. 



CONSOLE COMMUNICATION 

A single macro, CONSOLE, is provided for communication 
with the operator's console. This macro may be used both 
for sending messages to be typed on the console and for 
receiving replies from the console. 

A second macro, MESSAGE, is available to generate the 
actual message format, though this is not essential since 
the message could also be coded directly if desired (using 
Assembler data definition statements). 
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MESSAGES TO CONSOLE 

All messages to be sent to the console must conform to a 
standard format in memory. However, if the MESSAGE 
macro is used to create the message, the programmer need 
not be concerned with this format since it will be 
produced correctly by the macro. 

The MESSAGE macro should be coded in a data area of 
the user program using the parameters specified under the 
MESSAGE macro description in Section 6; it must be 
given a label so that it may be referenced by the 
corresponding CONSOLE macro. 

To transmit a message to the console, a CONSOLE macro 
must be coded using a DATBUF1=symbolic address 
parameter where the symbolic address is the tag on the 
MESSAGE macro used to generate the actual message. 



At assembly time the MESSAGE macro at LABELA will 
create a message format with a message text area 1 7 bytes 
long, the first byte of which will be labeled MSG. The 
first seven bytes contained in the message text area will 
be PHASE 1 and the remaining 10 bytes will be filled 
with blanks. 

During execution of the program, the first MOVX instruc- 
tion will move the characters COMPLETED into LABELA's 
message text area displaced eight bytes to the right of 
the label MSG, thus forming the message PHASE 1 
COMPLETED. The CONSOLE macro following this 
MOVX instruction will then cause the message to be 
typed out on the console. Similarly, the second MOVX 
instruction will result in the message PHASE 1 ABORTED, 
and the CONSOLE macro following the MOVX instruc- 
tion will send this message to the console. 



The format of the message as it will be typed on the con- 
sole is as follows: 



n ii 



messagetext 



n — the message number assigned by the system. 
This will be blank unless a reply is required. 
If a reply is required, this message number must 
be included by the operator in the reply state- 
ment. 

ii — a two-character operating system source 
indicator: PI means partition 1, P2 means parti- 
tion 2,# # means operating system. 

t — a one-character message type indicator: 
I means informative, D means directive (re- 
quiring operator action). This is obtained from 
the type specified in the MESSAGE macro. 

messagetext — the actual message, up to 100 
EBCDIC characters (bytes) long. 
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REPLIES FROM CONSOLE 

The link between a given output message and its 
corresponding reply message is established by a message 
number which is the first character in both the message 
and its reply. This number is assigned by the system and 
typed with the output message if the message requires a 
reply (otherwise the first character position will be left 
blank). 



When the operator types the reply, the following format 
is used: 

n replytext 

n - the number of the output message to which 
the operator is replying. 

replytext - the actual reply, up to 100 
EBCDIC characters (bytes) long. 

The reply will be received by the same CONSOLE macro 
that issued the output message. (In addition to the 
DATBUF1=symbolie address parameter, a CONSOLE 
macro that is intended to receive a reply must also include 
a DATBUF2=symbolic address parameter to signal the 
system that a reply is required and to direct it to the reply 
buffer area.) 

Note that when a CONSOLE macro requires a reply, 
control will not be returned to the user program until a 
reply has been received unless RETURN=YES is coded to 
specify immediate return. 
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Example 
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At assembly time the MESSAGE macro at LABELA will 
create an output message format containing the message 
text ENTER PASSWORD, and the MESSAGE macro 
at LABELB will create a reply message format contain- 
ing a 10-byte field reserved for the reply message text. 

During the execution of the program, the CONSOLE macro 
will cause the message 5 P1 D ENTER PASSWORD to 
be typed out on the console. The system has included 
the message number (5 for this example) so that the 
operator's reply (which will use the same prefix) 
may be linked to the correct output message. When 
the operator enters his reply (for example, 5 molybdenum), 
the reply will be transferred to the 10-byte field re- 
served for it by LABELB. 
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5. PROGRAM DEBUGGING 



Included in the operating system is a debug package, 
known as CHECKOUT, for assistance in debugging 
Assembler language* programs. CHECKOUT enables the 
programmer, through debug request cards placed in his 
Control Language deck (as a data file), to call for a 
selection of register and main-storage dumps to be 
performed at specified points during the execution of his 
program. The following dynamic snapshots in 
hexadecimal format may be obtained. 



1. General registers 

2. Any specified area of the user program 

3. The entire user and system areas 

4. Formated system control information 



Before debugging requests may be applied to a program, 
the program must be assembled and linkage edited. 



* CHECKOUT may also be used with RPG.COBOL, and FORTRAN 
programs if an Assembler language listing of the compiler out- 
put is available. 



CHECKOUT OPERATION 

CHECKOUT operates in two phases. The first phase, 
performed immediately after the program segment to be 
debugged has been loaded, involves initializing the pro- 
gram by planting special debug service requests at 
appropriate points within it and building (within the 
system) the control information necessary for executing 
the debug request. (The nature and location of the 
planted service requests is determined by the debugging 
requirements supplied by the user with the Control Langu- 
age statements.) 



At this point, the directives are written on the job's 
SYSOUT file, accompanied by directive diagnostic 
messages, if any. 

The second phase, performed after the initialized pro- 
gram has been loaded and goes into execution, involves 
the processing of the previously planted service requests. 

Each debug service request overlays a user program 
instruction. This instruction is saved by CHECKOUT so 
that it may be replaced and executed on completion of 
the service request (to maintain the integrity of the user 
program). After the replaced instruction has been 
executed, the Control Program reestablishes the debug 
service request in preparation for the next time through 
the program (if any). 
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REQUESTING DEBUGGING SERVICES 



BREAK DIRECTIVE 



Program debugging services are requested entirely through 
the use of request cards which are placed in the job 
deck with the Control Language cards (Figure 5-1). 
This arrangement enables specific requests to be altered 
from run to run without requiring repeated reassembly 
of the program being debugged. 

When debugging services are required, the //EXECUTE 
statement associated with the program to be debugged 
must always include the parameter DEBUG=YES. This 
instructs the system to load the CHECKOUT routines 
immediately after the program itself has been loaded 
and then to transfer control to CHECKOUT. 

The types of dumps required and the circumstances in 
which they are to be performed are specified in the set 
of debugging directives coded on the request cards. 



The BREAK directive specifies the type, location, and 
circumstances of a particular action in a debugging re- 
quest. There are three types of action that may be re- 
quested. 

1. Dump 

2. Program termination 

3. Setting or resetting of the condition flag 
(an indicator, maintained by CHECKOUT, 
used to govern the execution of condition- 
al requests*) 

The format of the BREAK directive is: 

BREAK=(breakpoint address.action 
[.type] [, interval] 
[.starting address.ending address] ) 



* For a more detailed discussion, refer to Conditional Request 
paragraph. 




Figure 5-1. Job Deck with Debug Requests 
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breakpoint address 

A 1- to 4-digit hexadecimal code specifying the address 
within the program at which this particular BREAK 
directive is to come into operation. The breakpoint 
address must be an even number (on a word boundary) 
and must point to the first word of any valid instruction 
except an SR or a service request macro (for example, 
READ or WRITE). The breakpoint address must be 
specified as a displacement within the relevant load 
module. When a program consists of a single load module 
which was produced from a single control section (the 
normal case), this displacement may be obtained directly 
from the program's assembly listing, but when the 
program consists of multiple control sections/modules, 
the Linkage Editor map will also be required to calculate 
the additional control section displacements. 



action 



A 1- or 2-character code specifying the action to be per- 
formed at the breakpoint address. The following action 
codes are available. 



Code Action 

T Terminates program and dumps if type 

parameter is present 

TC Terminates if condition flag is on and 

dumps if type parameter is present 

D Dumps unconditionally 

DC Dumps if condition flag is on 

CS Turns condition flag on and dumps if 

type parameter is present 

CR Turns condition flag off and dumps if 

type parameter is present 



type (Optional) 

A 1-character code specifying the type of dump to be 
performed. The following type codes are available. 



Code 

R 
S 



Type 

General registers only 

General registers plus main-storage im- 
ages (in hexadecimal with EBCDICtrans- 
lations) of that section of the user 
partition defined by starting address 
and ending address 

General registers, formated! system con- 
trol information, and main-storage im- 
ages of the entire user partition 

General registers, formated system 
control information, and main-storage 
images of the entire user and system 
areas 



interval 



(Optional) 



A 1- to 3-digit decimal number (0-255) specifying the 
number of times the breakpoint address must be passed 
before the selected action is performed. No action will be 
taken on the first n-1 executions of the instruction at the 
breakpoint address; action will be taken on execution n, 
2n, 3n, etc. 



starting address.ending address (Optional) 

A pair of 1- to 4-digit hexadecimal codes specifying the 
starting and ending words of the main-storage dump. Both 
should be word addresses; if not, starting address and 
ending address will be rounded down one byte. Starting 
address and ending address must be specified as 
displacements within the partition. Starting and ending 
displacements are relative to the beginning of the user 
portion of the partition. The linkage editor map will be 
required to compute the actual offset. 
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Examples 



CONDITIONAL REQUESTS 



1. BREAK=(1064,D,R) 

When program execution reaches displace- 
ment 1064 (before executing the instruction 
at 1064), general registers are dumped. 

2. BREAK=(1098,CS) 

The condition flag is turned on when program 
execution reaches displacement 1098. 

3. BREAK=(1120,TC,S„2000,2080)* 

If the condition flag is on when displacement 
1120 is reached, the program terminates and 
the memory from partition displacements 
2000 to 2080 is dumped. If the condition flag 
is off at this time, no action is taken. 



A conditional request (BREAK directive) is a request 
which is only performed in the event that the condition 
flag, maintained by CHECKOUT, is in the on condi- 
tion at the time that the request is to be implemen- 
ted. This flag may be dynamically altered during program 
execution and may thus be used to govern the execution 
of conditional requests. 

The condition flag is always in the off state at the start 
of a program. If a BREAK directive is coded to set the 
condition flag to on at a breakpoint address within a 
given program path, a conditional dump will not be 
recognized unless the program has followed the given 
program path. As a result of the condition flag still 
being off, no conditional requests of the given program 
path will be honored (Figure 5-2). 



4. BREAK=(1250,D,R,40) 

For the first 39 executions of program 
displacement 1250, no action is taken. At the 
40th, 80th, 120th, etc., executions, the 
general registers are dumped. 



PROG DIRECTIVE 

The PROG directive establishes the name of the load 
module to which all succeeding directives apply, up to the 
point that a new PROG directive is encountered. Until the 
first PROG directive is reached, all BREAK directives 
automatically relate to the main module as specified in 
the //EXECUTE statement. Thus, the PROG directive is 
only necessary when debugging programs containing more 
than one load module. 

The format of the PROG directive is: 
PROG=program name 

program name 

The name of the load module to which all succeeding 
directives apply. 



EXAMPLE OF JOB CONTROL DECK WITH 
CHECKOUT DIRECTIVES 

Figure 5-3 shows a typical job deck including a CHECK- 
OUT directive set calling for a variety of different 
dumps. An explanation of each card follows: 

Card 1 : The //JOB card. 

Card 2: The //EXECUTE card includes the 
parameter DEBUG=YES so that the system will 
open the CHECKOUT data file and initialize 
CHECKOUT for each loaded module. 

Cards 3, 4, and 5: The //DEFINE cards identify 
the input file, output file, and CHECKOUT 
directive file, respectively. (Cards 3 and 4 are not 
required by CHECKOUT.) 

Card 6: The //DATA card informs the system 
that data destined for the CHECKOUT data 
file follows immediately. 



Card 7: The first of the CHECKOUT directive 
cards. The BREAK directive on this card di- 
rects CHECKOUT to turn the condition flag 
on when displacement 102A is reached within 
program COPY. (Since a PROG directive has 
not yet been issued, the program name given 
on the //EXECUTE card is assumed.) 



*The extra comma indicates that the interval parameter has 
been omitted. 
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SYSTEM ACTION 

Condition flag initialized to off when I 
new program is loaded by Control 
Language Services (at start of step | 

only). 



DEBUG REQUEST 



j Turn condition flag on at this 
i address. 



.J 



DEBUG REQUEST 



I DEBUG Rl 



Conditional dump at this address 
(will be performed only if Path B 
was taken). 



C END J 



Figure 5-2. Example of Use of Conditional Request 
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13/BREAK=(488.DC,A,150),BREAIH488,T„200) 



12/BREAK=(488,DC r S,5fl,1800,20B0),BREAK=<488,D,RI 



11/PROG=SEGMENT2,BREAK=<100B,CS) 



1D/BREAK=(12,D,R,10),BREAK=|888.T) 



9/BREAK=(17FE,T,A.15),PR0G=SEGMENT1 



8/8REAK=(102E,U,R,),BREAK=(104B,OC,S,,1000,180D) 



BREAK=(102A,CS) 



6/ //DATA FILE'CKDATA 



5/ //DEFINE IO=CHECKOUT,FILE=CKDATA 



4/ //DEFINE ID=OUTFILE.FILE=YOURDATA 



3/ //DEFINE ID=!NFILE,FILE=MYDATA 



2/ //EXECUTE PGM=COPY.DEBUG=YES 



//JOB NAME=FIL2FIL 



Figure 5-3. Typical Job Deck with Debugging Directives 



Card 8: This card contains two BREAK 
directives.* The first calls for a register file dump 
at displacement 102E within COPY. The second 
BREAK directive specifies a conditional dump of 
memory between partition displacements 1000 
and 1800, to be performed at displacement 104B 
within COPY only if the condition flag is on at 
this time. 

Card 9: The BREAK directive on this card 
requests program termination and a type A dump 
to be performed on every 15th execution of the 
instruction at program displacement 17FE. The 
PROG directive indicates that from here on (until 
another PROG is encountered) all BREAK 
directives are to apply to SEGMENT1. 

Card 10: The first BREAK directive calls for a 
register dump on every 10th execution of the 
instruction at displacement 12 within 
SEGMENT1. The second BREAK directive 
specifies termination of program at displacement 
888 within SEGMENT1. 



Card 11: From this point until another PROG 
directive is issued, all directives apply to SEG- 
MENTS The BREAK directive calls for the 
condition flag to be turned on at displacement 
1 000 within SEGMENT2. 



Cards 12 and 13: The four BREAK directives on 
these cards all apply to displacement 488 within 
SEGMENT2. The first specifies a conditional 
dump of memory locations between partition 
displacement 1000 and 2000, to be performed on 
every 50th execution of the instruction at the 
breakpoint address if the condition flag is on. The 
second calls for a register file dump on each 
execution. The third is a conditional dump of type 
A to be performed on the 150th execution. The 
fourth is an unconditional termination of the 
whole program on the 200th execution. 



Card 14: This is the data delimiter card for 
the CHECKOUT directive data file. 



*Note that multiple debugging directives may appear on one card, 
but no continuation is allowed. 



Card 15: The //EOJ card. 
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6. MACROS 



This section gives the specifications for the logical I/O 
level functions of Data Management, console communica- 
tions, and Control Program Services. In general, all the 
macros have the following format. 



Name 



Operation 



Operand 



DATA MANAGEMENT MACROS 

In this section only the logical I/O level of Data Manage- 
ment macros are given. This level of macros includes: 

• File and Label Definition Macros 



The name field is an optional field which contains a 1- to 
8-character alphanumeric file identifier. The first six 
characters must be unique to accommodate the standard 
suffixes used by the system. These are discussed in the 
Control Program and Data Management Services, 
Extended Reference manual. 

The names ident, labadr, and tag are used as identifiers for 
the software function specified in the operation field. 



DEFSF 
DEFRF 
DEFIF 
DEFLB 

File Control Macros 

OPENL 
CLOSEL 
CLOVE L 

Data Transmission Macros 



The operand field contains keyword parameters which 
may be in any order separated by commas. Optional 
parameters are denoted by brackets,! ]. Parameters with 
a choice of specifications are denoted by braces, { }, with 
the default case being underlined. 

Fields are free-form and are separated by blanks; thus, 
no imbedded blanks are allowed within the parameter 
string. If more than one card is necessary, a semicolon 
must appear after the last parameter on each card ex- 
cept the last. 

Symbolic address is the 1- to 8-character symbol used to 
identify a coding statement. Unless otherwise stated all 
numbers are assumed to be in decimal with no leading 
zeros. 



GET 

PUT 

SETL 

LOCRC 

PUTU 

DELR 

FILE AND LABEL DEFINITION MACROS 

The declarative macros for the logical I/O level define 
the blocking/deblocking and label information for the 
three logical I/O level organizations. There must be 
a file definition macro (DEFSF, DEFRF, or DEFIF) 
for each file to be opened and processed. The macros 
generate a main-storage table, the Buffer Description 
Table (BDT), which is used by the GET/PUT logic. 



The linkage conventions for MRX/OS are found in 
Appendix B. 



The name field (ident) of the define macros is a required 
entry. This 8-character file identifier is the symbolic 
address of the BDT generated by a macro instruction. 



6-1 



DEFSF - Define Sequential File 

The DEFSF macro defines sequential files. The format for 
DEFSF is as follows: 



Name Operation 



ident 



DEFSF 



[' 



BINARY= 



BLKFAC=n 
BLKSIZ=n 




[' 



_BUFSHR=5^ S [] 
[DATBUF1=symbolic address] 

DATBUF2= l Embolic address!] 

/■symbolic address "T 
ERROPT=<S 

= (STND H 

labtyp=<none > 
(nstnd\J 

[RECADR=symboHc address] 

jRECREG* 

RECSIZ^n 






^symbolic 



RECTYP 



■R! 



[«-"H^Q 



binary -{no S } 



(Optional) 



BINARY=YES indicates that files assigned to card readers 
will process binary cards; therefore, the buffer size must 
be 160 bytes rather than 80 (or in the case of punch, 161 
bytes rather than 81). If BINARY=NO or if omitted, the 
data is in EBCDIC. 



BLKFAC=n 

Designates the number of records per block (blocking 
factor). The keyword value gives an integer value of 1 
through 255. BLKFAC is required for fixed length 
records. This parameter should be used for variable length 
records only when packing is not desired; without it, 
packing will occur. 

BLKSIZ=n 

Specifies the block size of the file. The keyword value 
gives an integer value of 18 bytes through 32K bytes for 
magnetic tape and 7294 bytes for disc. The four bytes per 
record for record headers must be included when 
specifying block size for files which may be assigned to 
disc or magnetic tape. Buffer size must be greater than or 
equal to the block size of any file which uses the buffer. 



8UFSHR={^ S } 



(Optional) 



BUFSHR=YES indicates the I/O buffer(s) is(are) shared 
with another file. If sharing is specified, the buffer 
address(es) must be explicitly specified and the user must 
reserve two bytes (one machine word) immediately before 
DATBUF1. This word, containing zero, is used by OPENL 
and CLOSEL to resolve buffer usage conflicts. If 
BUFSHR=NO or is omitted, I/O buffers are not shared. 
OPENL and CLOSEL do not check for buffer usage 
conflicts. 



DATBUF1=symbolic address 



(Optional) 



Specifies the address of the first I/O buffer, which must 
begin on an even byte boundary. When generating 
buffers, the buffer size must be greater than or equal 
to the block size of any file which uses the buffer. 
If the parameter is not specified, DEFSF generates 
a buffer equal to block size immediately following the 
BDT. 



DATBUF2=( YES . .. . . J 
{symbolic address) 



(Optional) 



Specifies a second I/O buffer, which permits overlapping 
of data transfer and information processing. The buffer 
mu3t begin on an even byte boundary. DATBUF2=YES 
results in generation of a second buffer following 
DATBUF1. If omitted, processing is from one buffer. 



(symbolic address) 
ERROPT=<S 



(Optional) 



Specifies one of three conditions for processing errors. 
The symbolic address gives the user control when errors 
occur. The S (skip) option and I (ignore) option (only for 
input files) skips to the next block or ignores errors, 
respectively, and processing continues. If the parameter is 
omitted, error conditions abort the job. 



C STND ) 

labtyp=<none > 
(nstnd) 



(Optional) 



Determines the type of tape label processing to be per- 
formed for tape files. The parameter is ignored for non- 
tape files. The default value for files assigned to tape is 
standard label processing. The code definitions are: 
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Code Definition 

STND Check labels for input files. Write stan- 
dard labels for output files. 



VERIFY ={^ S } 



(Optional) 



NONE No labels exist and no label checking is 
done. 

NSTND Nonstandard labels exist and label check- 
ing is bypassed. The nonstandard label 
set must be terminated by a tape mark. 
The tape is positioned to the record 
following the tape mark by the OPENL 
macro. 



RECADR=symbolic address 



(Optional) 



Specifies the address of a record area. The size of the 
record area must be greater than or equal to RECSIZ. 
Record area address may also be specified at GET/PUT 
time. 



RECREG 



J YES) 



(Optional) 



RECREG=YES indicates processing without a record area. 
When RECREG=YES, R1 contains the address of a logical 
input record that is available for processing after a GET or 
the address of the area that is available for construction of 
the next logical record before a PUT. If this parameter is 
omitted or if RECREG=NO, a record area (RECADR 
parameter) must be specified in the DEFSF or at 
GET/PUT time. 



RECSIZ=n 

Indicates the record length (in bytes) for fixed length 
records. The keyword value gives an integer value of 18 
bytes through 32K bytes for magnetic tape and 7294 
bytes for disc. The maximum record length must be 
specified for variable length records. Record length does 
not include the header length. 



RECTYP= 



<8 



Specifies the record type, fixed (F) or variable (V) length, 
for the file. If omitted, records will be fixed length. 
If the file is assigned to cards or printer, the record 
type must be fixed. 



~VERIFY=YES states that a disc write verification will be 
done. If the file is not on disc, VERIFY is ignored. If 
omitted or VERIFY=NO, write verification is not used. 



Example 



■» 




OPERATION 




OPERAND 


I 2 3 4 5 fi 7 it 


9 


ID 11 12 11 14 IS IB 17 


IS 


19 2P 21 22 3.3 24 20 213 27 2B 29 3D 31 3? 33 34 35 3fi 57 JS 31 QQ fli 4? 4:1 Hi 4h 4K 


CAM././/. 




DEFSF, .... . 




8l,K,$rZ=JA ) ,EM.cP,T-,£#.(l.CA l X 

g£&SJZ.Kla,.t££J?X.I>.' t l : .,.i. ...... 

6.L.K F.AO.-.J. ,._....,, 



CARDIN is a sequential card file which is fixed length 
with block and record sizes of 80 bytes each. An error 
routine, ERRCD, processes any incorrect cards. 



DEFRF- Define Relative File 

The DEFRF macro defines relative files. The format for 
DEFRF is as follows: 



Name Operation 



ident 



DEFRF 



Operand 

ACCESS=j|{ 

[BLKFAC=n] 
BLKSIZ=n 

[DATBUF1 ^symbolic address] 



DATBUF2 



IYES 



(symbolic address 
/■symbolic address 



I] 



ERROPT=<S 

KEYADR=symbolic address 
_RECADR=symbolic address] 



RECREG 
R _ ECSIZ=n 
RECTYP 



} 



■@] 



-® 



[START=X] 
[END=Y] 

ver HS s 



It 

[' 
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{1} 



ACCESS* 



Specifies sequential (S) or random (R) access mode. 
Together with the usage parameter of OPENL, it 
determines the processing environment of the file. If 
omitted, access is sequential. 



DATBUF2= Wmbolicaddressj 



(Optional) 



Specifies a second I/O buffer, which allows overlapping of 
data transfer with information processing for sequential 
access. DATBUF2 is ignored for random access. If 
present, DATBUF2 must begin on an even byte boundary. 
DATBUF2=YES generates the buffer following 
DATBUF1. If DATBUF2 is omitted, processing if from 
one buffer. 



BLKFAC=n 



(Optional) 



Designates the number of records per block (blocking 
factor). The keyword value gives an integer value of 1 
through 255. When omitted, the blocking factor is 
determined by block size and record size. When BLKFAC 
is used, the relationship BLKSIZ>BLKFAC(RECSIZ+4) 
must be true. 



BLKSIZ=n 

Specifies the block size of the file. The keyword value 
gives an integer value of 18 bytes through 32K bytes for 
magnetic tape and 7294 bytes for disc. The block size 
includes record headers for disc or tape files. 



BUFSHR={^ S } 



(Optional) 



BUFSHR=YES indicates the I/O buffer(s) is(are) shared 
with another file. If BUFSHR=YES, the buffer address(es) 
must be explicitly specified and two bytes (one machine 
word) must be reserved immediately before DATBUF1. 
This word, containing zero, is used by OPENL and 
CLOSEL to resolve buffer usage conflicts. If 
BUFSHR=NO or if omitted, buffers are not shared, and 
OPENL and CLOSEL do not check for conflicts. 



( symbolic address) 
ERROPT=jS > 



(Optional) 



Specifies one of three conditions for processing errors. 
The symbolic address gives the user control when errors 
occur. The skip (S) option and ignore (I) option, for input 
files, skips to the next block or ignores errors, 
respectively, and processing continues. S is illegal for 
random access. If ERROPT is omitted, error conditions 
abort the job. 



KEYADR=symbolic address 

Gives (for random access) the address of the location that 
will contain the number of the record to be processed. 
KEYADR is ignored for sequential access. The symbolic 
adoress for KEYADR is a 4-byte location beginning on an 
even byte boundary. 



RECADR=symbolic address 



(Optional) 



Specifies the address of the record area. Record areas may 
also be specified at GET/PUT time. They are required for 
random output to a blocked file. The size of the record 
area must be greater than or equal to RECSIZ. 



RECREG ={^Q S } 



(Optional) 



DATBUF1=symbolic address 



(Optional) 



Specifies the location of the first I/O buffer, which must 
begin on an even byte boundary. If DATBUF1 is omitted, 
the buffer immediately follows the BDT. The buffer size 
must be greater than or equal to the block size of any file 
which uses the buffer. 



RECREG=YES defines processing without a record area. 
When RECREG=YES, R1 contains the address of a logical 
input record that is available for processing after a GET or 
the address of the area that is available for constructing 
the next record before a PUT. If RECREG is omitted or if 
RECREG=NO, a record area must be defined either in the 
DEFRF macro at GET/PUT time. If random output is 
selected with RECREG=YES, the blocking factor must 
equal one. 
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RECSIZ=n 



DEFIF - Define Indexed File 



Indicates the record length (in bytes) for fixed length 
records. The keyword value gives an integer value of 18 
bytes through 32K bytes for magnetic tape and 7294 
bytes for disc. For variable length records, the record 
length is the maximum record length permitted. Record 
length does not include the header length. 



■ft} 



RECTYP' 



Denotes the record type, fixed (F) or variable (V) length, 
of the file. The default value is fixed length. 



START=X 



(Optional) 



States the logical limit, which may range from 1 to 2 32 -1 
(decimal), for the beginning of processing. At creation, 
this limit becomes the permanent offset for relative 
addressing. If START is used, the END parameter must 
also be used. 



END=Y 



(Optional) 



The DEFIF macro defines indexed files. The format for 
DEFIF is as follows: 



Name Operation 



ident 



DEFIF 



Operand 



ACCESS 



■II! 



[BLKFAC=n] 
BLKSIZ=n 

[DATBUF1=symbolic address] 

(symbolic addressf] 

Iyes ij 

*ERR0PT=j; Vmb0liCaddr9SS jl 

INDBUF={ YES U ,. . . 1] 
(symbolic address I J 



DATBUF2= 



INDSHR 



(YES 



1] 



(NO 
INDSIZ=n 

[INMAIN=symbolic address] 
KEYADR1=svmbolic address 
[KEYADR2=symbolic address] 
KEYSIZ=n 
[RECADR=symbolic address] 

RECSIZ=n 



tr 

[' 



States the logical limit for ending processing, where YJJX. 
(X is the START parameter limit.) Limits are decimal 
numbers. 



VERIFY 



jYESi 
(MS/ 



(Optional) 



VERIFY=YES states that a disc write verification will be 
done. If omitted or VERIFY=NO, write verification is not 
used. 



ACCESS* 



41} 



Specifies sequential (S) or random (R) access mode. 
Together with the usage parameter specified in the 
OPENL macro, this parameter determines the processing 
environment of the file. If omitted, processing is 
sequential. 



Example 



„„, 


OPE HAT (UN 




— u- 


1 2 3 4 b 6 7 8 


11) 11 12 13 14 15 1fi 11 


IB 


19 Z0 21 1.1 23 24 2b 26 27 23 29 30 31 32 33 34 35 36 3? 38 33 ID 41 42 13 44 45.46 


rtfioV. . . 


D.E.F.8.F. . . 




kil££&=.lCjAjis.i,Z*Ae.i,,.i 

Ke.i.AM:Ke.t.l.S.,AeCJSJ.z.*i.Cji. J l. . , , 
&£CTJi.P.*.F.,.V.&t.ie.2..=.tl,eS. ., ^ . ........ 



BLKFAC=n 



(Optional) 



Indicates the number of records per block (blocking 
factor). The keyword value gives an integer value of 1 
through 255. When not specified, the blocking factor is 
determined by the block size and record size. When 
BLKFAC is used, the relationship BLKSIZ>BLKFAC 
(RECSIZ+4) must be true. 



BLKSIZ=n 



MPLOY is a relatively organized file which allows random 
access through a key name, KEYIS. Although the fixed 
length record size is 100 bytes, the block size is 104 
bytes, which includes the record header. Write verification 
is specified. 



Specifies the block size of the file. The keyword value is 
in integer value of 18 bytes through 7294 bytes for disc. 
BLKSIZ must include the space for record headers. 
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BUFSHR 



YES) 



,JYE! 
(NO 






(Optional) 



BUFSHR=YES specifies that the I/O buffer is shared with 
another file. If BUFSHR=YES, the buffer address must 
have been explicitly specified and one word immediately 
before DATBUF1 must be reserved. This word contains 
zero and is used by OPENL and CLOSEL to resolve buffer 
usage conflicts. If omitted or BUFSHR=NO, buffers are 
not shared, and OPENL and CLOSEL do not check for 
conflicts. 



DATBUF1=symbolic address 



(Optional) 



INDSHR=< Y - S > 



INS / 



(Optional) 



INDSHR=YES indicates that the index buffer is shared 
with the data file buffer. Access must be random, 
DATBUF1 must be specified, and RECREG must not be 
specified. If omitted or INDSHR=NO, no index buffer 
sharing occurs. 

INDSIZ=n 

Specifies the index block size. The value n ranges from 18 
bytes to 7294 bytes. 



Designates the address of the first I/O buffer, which must 
begin on an even byte boundary. The buffer size must be 
greater than or equal to BLKSIZ when the user generates 
his own buffer. If DATBUF1 is omitted, a buffer is 
generated following the BDT. 



DATBUF2; 



/symbolic address) 
IYES J 



(Optional) 



INMAIN=symbolic address 



(Optional) 



Specifies the address in main storage where the directory 
to the directory index entries are read into from mass 
storage. This option expedites random processing. For 
sequential access, this parameter is ignored. 



KEYADR1=symbolic name 



Specifies a second I/O buffer, which permits overlapping 
of data transfer with record processing. If present, 
DATBUF2 must begin on an even byte boundary. 
DATBUF2=YES generates the buffer following 
DATBUF1. If DATBUF2 is omitted, processing is from 
one buffer. 



ERROPT 



/symbolic address) 



\l 



] 



(Optional) 



Specifies one of the two conditions for processing errors. 
The symbolic address gives the user control when errors 
occur. The ignore (I) option, only for input files, ignores 
errors and processing continues. If ERROPT is not 
specified, error conditions abort the job. 



Specifies the address of the location containing the primary 
key value of a record to be: 

1. Updated, retrieved, added, or deleted when 
in random mode 

2. Updated, added, or deleted when in sequen- 
tial mode 



KEYADR1 is required for record addition in sequential 
mode, optional for update in sequential mode, and 
ignored for input only in sequential mode. It is required 
for access in random mode. 



KEYADR2=symbolic address 



(Optional) 



INDBUF; 



JYES ) 

(symbolic address) 



(Optional) 



Specifies the address of a buffer to be used by the system 
for processing of index blocks. If this parameter is 
omitted for random access, INDSHR=YES must be 
specified. INDBUF=YES causes automatic buffer 
generation. 



Specifies the address of the location which contains the 
primary key value of the record after a GET (forward 
key) that will be obtained on the next GET. When the end 
of file is reached, the first two bytes of the location 
specified by KEYADR2 will be set to FFFF16 to indicate 
an EOF. This allows records to be added at the end of the 
file. KEYADR2 is optional for sequential access and 
ignored for random access. 



KEYSIZ=n 



Specifies the length (in bytes) of the primary key. The 
value n ranges from 2 to 100 bytes. 
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RECADR=symbolic address 



(Optional) 



Specifies the address of a record area. The record area size 
must be greater than or equal to RECSIZ. It is required 
for random output to a blocked file using PUT. Record 
areas may also be specified at GET/PUT time. 



PARTLST is an indexed file open for random access 
through KEYNAM. The keysize is five bytes. The block 
size is 94 which is the record size plus four bytes for the 
control header. The index block size is 250 bytes. If an 
error is detected, the error routine MISTAK receives 
control. A write verification will be done. 



RECREG=< YES \ 
(NO j 



(Optional) 



RECREG=YES specifies processing without a record area. 
When RECREG=YES, R1 contains the address of a logical 
input record after a GET or the address available for 
constructing the next record before PUT or PUTU. If 
omitted or RECREG=NO, a record area must be specified 
either in the DEFIF macro or at GET/PUT time. Table 
6-1 indicates when RECREG may be used. 

Table 6-1. RECREG Use 



\\^ Usage 
Access ^n- 


Input 


Update 


Output 


Sequential 


Any BLKFAC 


BLKFAC 
of I 


Any BLKFAC 


Random 


Any BLKFAC 


BLKFAC 
of I 


Illegal 



Summary of File Definition Parameters 

Table 6-2 summarizes the parameters for sequential, 
relative, and indexed files. 



DEFLB- Define Label 

The DEFLB macro generates file label data into a 
main-storage buffer for creating and checking disc labels. 
The logical I/O level file control macros may use DEFLB, 
but it is not necessary to define labels at the logical I/O 
level. The format for DEFLB is as follows: 



Name Operation 
labadr DEFLB 

FILENAM=name 



Operand 

FILENAM=name 
[MSC=code] 



RECSIZ=n 

Specifies the fixed record length in bytes. The value n 
ranges from 18 bytes to 7294 bytes. The record length 
does not include the header length. 



Specifies a 1- to 17-character alphanumeric file name. The 
first character may be A-Z, 0-9, or $. Imbedded dashes are 
allowed, but not imbedded blanks. Index file names are 
created by adding an asterisk at the end of the associated 
data file name. 



VERIFY=/ YES l 



(NO f 



MSC=code 



(Optional) 



Designates a 4-byte EBCDIC modification security code, 
which is used only for work and permanent files. If 
omitted, blanks are assumed. 



VERIFY=YES states that a disc write verification will be 
done. If omitted or VERIFY=NO, no write verification is 
done. 

Example 



«.« 


OPERATION 
10 11 1? 13 14 lb K 17 


OPERAND 


12 3 4 b Ei 7 a 


S ID 21) 21 11 23 24 25 26 27 28 2fl 30 31 32 33 is 35 36 37 3B 30 1(1 41 42 43 14 15 415 


PMTX.ST 


beeiF ... 


SAfiAPT.rAl STAM, Vlfij FH-y^il , . 

Ke.VAb/ii'KeyMiLti.M.CAi i*,i.o.J. , 



Example 



NAME 




OPERATION 




OPERAND 


12 3 4 5 6 7 3 


9 


10 11 12 U 14 IS IE 17 


i« 


19 20 21 22 23 24 25 20 27 23 2D 30 31 32 33 3* 35 3C 37 38 3D 40 41 42 43 44 45 46 


T_hf£X. . . 




0X6tA..... 




FJX&fi(Ml=PA2£.QML 



TAPE1 gives the label identification for a file named 
PAYROLL. 
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Table 6-2, File Definition Parameters 



LOGICAL I/O FILE CONTROL MACROS 



\> File 
\Type 

Parameter ^\ 


Sequential 


Relative 


Indexed 


ACCESS 




Required; 

default 

sequential 


Required; 

default 

sequential 


BINARY 


Optional 
for card 
devices 






BLKFAC 


Optional; 
default is 
packing 


Optional 


Optional 


BLKSIZ 


Required '•.'■ 


' Required 


Required 


BUFSHR 


Optional 


Optional 


Optional 


DATBUF1 


Optional; 
default 
follows 
BDT 


Optional; 
default 
follows 
BDT 


Optional; 
default 
follows 
BDT 


DATBUF2 


Optional 


Optional 


Optional 


END 




Optional 


Optional 


ERROPT 


Optional 


Optional 


INDBUF 


|:': ; ii;l:: ; i::^|;:|;l::;|ii|:: 




Required 
for 

sequential 
access 


INDSHR 






Optional 


INDSIZ 






Required 


INMAIN 






Optional 


KEYADR(I) 




Required 
for ran- 
dom access 


Required 
for ran- 
dom access, 
sequential 
update, 
sequential 
output 


KEYADR2 






Optional 


KEYSIZ 






Required 


LABTYP 


Tape files 
only 






RECADR 


Optional 


Optional 


Optional 


RECREG 


Optional 


Optional 


Optional 


RECSIZ 


Required 


Required 


Required ; 


RECTYP 


Required; 

default 

fixed 


Required; 

default 

fixed 


Fixed 
length 


START 




Optional 


" ; .;. \ i : : : : ; : : ;:: 


VERIFY 


Optional 


Optional 


Optional 



The file control macros (OPENL, CLOSEL, and CLOVEL) 
direct data transmission at the logical I/O level. 

The functions of the OPENL macro are as follows: 

• Opens the file for data transmission by 
establishing an FDT 

• Records BDT entries not supplied by DEFSF, 
DEFRF.orDEFIF 

• Catalogs logical level file attributes when 
files are opened for output for the first 
time 

• Checks file attributes supplied through 
DEFSF, DEFRF, or DEFIF against perman- 
ent cataloged attributes on subsequent opens 

• Prefills buffers for sequential access by GET/ 
PUT requests 



The CLOSEL macro closes files to data transmission and 
empties buffers for GET/PUT when required. 

The CLOVEL macro closes disc or magnetic tape volumes 
and switches to the next volume before the end of the 
allocated disc space or end of tape marker is reached. 
End of allocated area volume switching is performed 
by the GET/PUT logic through the CLOVEL macro. 



OPENL - Open Logical File 

The OPENL macro opens a file for logical I/O processing. 
The format for OPENL is as follows: 



Name Operation 
[tag] OPENL 



Operand 

IDENT=name 
[cONTRO L =g |v j] 
[LABDEF=symbolic address] 



REWIND^ 



USAGES U 



■m] 
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IDENT=name 

Specifies the file identifier. It must correspond to the 
name field (file identifier) of a DEFSF, DEFRF, or 
DEFIF macro. 



CONTROL* 



INATIVEJ 



JANS 



(Optional) 



USAGEHU 
(0 



(Optional) 



Determines input, update, or output processing. Update 
usage is allowed for sequential files only if the record type 
is fixed length and the file is assigned to mass storage. The 
default value is I. 



CONTROL=NATIVE indicates that the control characters 
are native to that device. ANSI control characters are used 
if omitted or CONTROL=ANS. 



LABDEF=symbolic address 



(Optional) 



Specifies the address of the main-storage buffer that 
contains a file label. The symbolic address should be 
identical to that specified in the label address name field 
of a DEFLB macro. For disc files, label information may 
have been specified by Control Language //DEFINE 
statements which override LABDEF information if both 
are present. This parameter may not be used for 
permanent files or work files with update or output usage. 
For temporary or scratch files, the filename is 
concatenated with the job name. It is ignored for files 
assigned to unit record devices or magnetic tape. 



, ,„,. (YES) 
UST iNO ) 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of general-purpose register 6 (R6) with the address 
of the parameter packet and general-purpose register 7 
(R7) with the save area address is a user responsibility. If 
the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 



REWIND={^ 



(Optional) 



REWIND=NO specifies that no initial rewind will be 
performed. This parameter is ignored for non-tape files. If 
REWIND=YES or if omitted, initial rewind is performed. 



Example 



HAMS 


OPtKATION 


oHRMKt 


1 1 3 4 S 6 J » 


JO 11 12 13 14 IB IB 11 


( 19 !0 :i 2!!3 24 25 W J? It 13 30 31 3* 33 M 3B 36 37 31 39 40.41 « 43*4*6.46 




OtSJiJL. 


rogyr^Agfli^ 'usAy J. . . 















OPENL opens the input file CARDIN for processing. 



CLOSEL - Close Logical File 

The CLOSEL macro closes a file to logical I/O processing. 
The format for CLOSEL is as follows: 



Name Operation 
[tag] CLOSEL 



Operand 



IDENT=name 



LIST- 



(YES 

(NO 







.— SI] . 

REWiND-j^jJ 



IDENT=name 

Specifies the file identifier. 



H~) 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 
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«*H£} 



(Optional) 



Indicates the disposition of the file, When the parameter is 
not specified or LOCK=NO, the file may be reopened 
from within the same job; tape files are rewound. When 
LOCK=YES, OPENL may not be executed again during 
the same job; tape files are unloaded. 



(yes) 

REWIND-*— j- 



(Optional) 



REWIND=NO specifies that no rewind will be performed 
after closing the file. This parameter is ignored for 
non-tape files. If REWIND=YES or if omitted, initial 
rewind is performed. 

Example 



i 2 3 4 5. 6. t, ■ 



10 11 II 13 1* <b K 17 



CAOAfiL 



If IS H 21 22 23.24 25 26 .27. 28.29.311. H 32 33 34 35 38 37 31 39 40. 41 42.m4.45.46 



IOBNT'OPLO^ 



H~} 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 

Example 



NAM! 




OPERATION 




OWH AMP 






[0 11 12 13 H IS 16 17 


II 


19 20 21 22 » 2* 25 26 27 21 29 30 SI 32 33 34 3S 3G 37 39 19 40 4? 42 43.44 «. 49 




-CUUOU..— 




1£UU£t*TAPf?LL. . . . . ^ ^ - 















CLOVE L switches volumes in a multivolume file called 
TAPFIL 



CLOSE L closes the file MPLOY to any further proc- 
essing. 



CLOVEL - Volume Switching 



DATA TRANSMISSION MACROS 

The data transmission macros - GET, PUT, and associated 
macros — control the transmission of data to and from 
the different files. 



The CLOVEL macro performs volume switching. It is 
used for sequential multivolume files assigned to tape or 
disc and should be used only to prematurely close a 
volume and switch to the next sequential volume. Volume 
switching at EOV is performed automatically by the 
GET/PUT modules. 

CLOVEL performs header and trailer label processing on 
tapes, alternate unit processing on tapes, and disc pack 
mounting and demounting (via operator control). The 
format for CLOVEL is as follows: 



Table 6-3 lists the GET/PUT macros allowed according to 
file type and usage. 



GET - Get Record 

The GET macro makes a logical record available in a 
record area. When no record area is present, the address 
of an available logical record in an I/O buffer is pro- 
vided in R1. The format for GET is as follows: 



Name Operation 
[tag] CLOVEL 

IDENT=name 

Specifies the file identifier. 



Operand 
IDENT=name 



Name Operation 



[tag] 



GET 



Operand 

IDXSA=YES 

IDENT=name 

[RECADR=symbolic address] 
[RECSIZ=symbolic address] 
[RTNADR=symbo!ic address] 
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Table 6-3. GET/PUT Macro Usage 



\. Macro 
File\ 
Type V 
& Usage >v 


GET 


PUT 


LOCRC 


PUTU 


SETL 


DELR 


Sequential 
Input 
Update 
Output 


X 
X 


X 
X 










Relative 
Input 
Update 
Output 


X 
X 


X 
X 


X 
X 
X 








Indexed 
Input 
Update 
Output 


X 
X 


X 
X 




X 


X 
X 


X 



IDXSA=YES 



RECSIZ=symbolic address 



(Optional) 



Specifies sequential processing of indexed files; it is 
ignored for random processing. If IDXSA is omitted for 
sequential processing, control is given to the user's error 
routine or the job aborts. 

IDENT=name 



Specifies the address of a location that will contain the 
size (in bytes) of the logical record upon return. RECSIZ 
is ignored for fixed length records. It must specify an 
even byte boundary. 



RTNADR=symbolic address 



(Optional) 



Specifies the file identifier. 



HE"} 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NQ, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 



RECADR=symbolic address 



(Optional) 



Specifies the address of a record area. When RECADR is 
present in the GET macro, it overrides any RECADR 
specified in a DEFSF, DEFRF, or DEFIF macro. 



Specifies the address of a user routine which receives 
control when a sequentially processed file reaches the end 
of file or a randomly processed file contains an invalid key 
value in the KEYADR1 address. When RTNADR is 
omitted, control is given to the error option selected in 
the ERROPT parameter of the define macro. If no 
ERROPT was specified, the job will abort. 



Example 



NAME 




™.™ 




„™» 


1. 2 3 4 5 fi 1 a 


3 


11) 11 13 13 14 IS 16 17 


18 


IS JO ?1 22 23 24 2b 2H 27 28 ?9 3D 31 32 33 34 35 36 37 38 33 411 41 42 43 41 45 46 






Q£T 




ll>.EM.T.=CAAbjjf^lTM.i>A'M^£ ... . 



The GET macro reads the CARDIN file until the DONE 
parameter is satisfied. 
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PUT - Put Record 



RECSIZ=symbolic address 



The PUT macro moves a logical record from a record area 
into an I/O buffer or indicates that a logical record has 
been generated by the user in an I/O buffer. PUT is used 
to update records for sequential and relative files. The 
format for PUT is as follows: 



Specifies the address of a location that contains the size 
(in bytes) of the logical record. RECSIZ must specify 
an even byte boundary. It is ignored for fixed length 
records. When RECSIZ is absent and the records are 
of variable length, control is given to ERROPT or the 
job aborts. 



Name Operation 



[tag] 



PUT 



Operand 



IDXSA=YES 
IDENT=name 

[RECADR=symbolic address] 
[RECSIZ=symbolic address] 
[RTNADR=symbolic address] 



! |] 



RTNADR=symbolic address 



(Optional) 



Specifies the address of a user routine which receives 
control when the end of allocation or a key error 
occurs. When RTNADR is not defined, control goes to 
the addresses specified in the ERROPT parameter of the 
define macro. If ERROPT was not specified, the job aborts. 



IDXSA=YES 

Specifies sequential processing of indexed files; it is 
ignored for random processing. If IDXSA is omitted for 
sequential processing, control is given to the user's error 
routine or the job aborts. 



Example 



1 ! it H J i 



10 11 12 11 M IS 10 U 



18 18 20 21 22 33 24 25.20 V, 23 29 20. 31 32.33 34 3B. 36 37 3B 39. 40.41 42.4344 45.40 



*t« ate.Bg, fceegiz- site 



The PUT macro writes the file RECRD according to the 
byte size found in SIZE. 



IDENT=name 

Specifies the file identifier. 



H£} 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 



SETL - Set Limits 

The SETL macro establishes an initial key value for 
sequential access of indexed files. If SETL is not issued, 
retrieval starts at the logical beginning of the file. The 
format for SETL is as\follows: 



Name Operation 
[tag] SETL 



Operand 

IDENT=name 
KEYERR=symbolic address 

JKEY ^ 
START=< GKEY > 



UOF f 



IDENT=name 

Specifies the file identifier. 



RECADR=symbolic address 



(Optional) 



Specifies the address of a record area. When RECADR is 
present in the PUT macro, it overrides any RECADR 
specification in a DEFSF, DEFRF, or DEFIF macro. 



KEYERR=symbolic address 

Specifies the address which receives control when START= 
KEY and there is no key value specified. This parameter 
is required for START=KEY; otherwise, it is ignored. 
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H™} 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 

(KEY i- 

start=]gkey[ 

(BOF > 

Determines where the retrieval begins according to the 
following codes. 

Code Option 

KEY Retrieval begins with the record having 
the key value contained in KEYADR2 
of the tagged DEFIF macro. If no data 
record with this key exists, control 
returns to KEYERR. 

GKEY Retrieval begins with the record having 
the key value contained in KEYADR2, 
or if no record having this value exists, 
it begins with the record having the next 
greater value. If no record has a greater 
key value, KEYADR2 receives FFFF-|g' 
indicating the end of the file. This per- 
mits records to be added to the end of 
the file. 



LOCRC — Locate Record 

LOCRC is a relative record seek macro. A seek operation 
is issued to the block containing the record number found 
in the location specified by the KEY ADR parameter of 
the DEFRF macro. LOCRC is used to overlap seek and 
processing time for random access. If an error condition 
arises, the following GET/PUT receives the status by 
having control returned to the invalid key routine. The 
format for LOCRC is as follows: 



Name Operation 
[tag] LOCRC 



Operand 



!DENT=name 



IDENT=name 

Specifies the file identifier. 



, .__ (yes) 
list= {no I 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 



BOF Retrieval begins at the beginning of the 
file. 



Example 



Example 



NAME 


_. 


» I ft A.N D 


1 7. 3 A i 6 1 6 


ID 11 12 13 14 15 16 11 






$£TA . . 


IQEta.*f>ATMi:,.3XMLTj>.mP^^-~.-. 






_J_ L _. ■ . J , 









The SETL macro is used with a GET to establish the 
beginning key value for indexed files. In this case, re- 
trieval will begin at the beginning of the file named 
PRTLST. 



H»MS 




OM RATI DM 




ON HAND 


1 2 3 1 5 S T 8 


9 


10 11 12 13 14 15 IB VI 


IB 


19 20 21 22 23 24 2b 2B 27 3D 29 3D 31 32 33 34 35 36 3J 38 39 40 41 41 43 44 45,48 


__ _j 




L.e&te , 




20£W7>MPijQy . - 



The LOCRC macro positions the access mechanism at the 
location on the disc file which contains the record. 
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PUTU - Put Update 



Example 



The PUTU macro updates a record in indexed files and 
rewrites the record retrieved by the preceding GET. The 
address specified by KEYADR in the DEFIF macro 
must contain the key value of the record to be changed. 
If the key value in KEYADR is not identical to the 
key value of the record obtained in the previous GET, 
control goes to the invalid key routine. The format for 
PUTU is as follows: 



Name Operation 



[tag] 



PUTU 



Operand 

IDENT=name 
KEYERR=symbolic address 

|YES| 

'NO 



QHro 



LIST= 
[RECADR=symbolic address] 



IDENT=name 

Specifies the file identifier. 

KEYERR=symbolic address 

Specifies the address which will receive control when a 
key error occurs. 



H»} 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 



NAMI 




Of* RATI DM 




OP in AND 


1 2 3 * 5 6 7 3 


I 


10 11 12 13 14 15 IS 17 


t« 


19 20 21 22 23 24 25 26 27 28 IS 30 31 12 33 34 35 3fl 3T 3! SS 10 41 42 13 « 45.48 






Puru . 




iamT'&E<GQ t *£¥£1lJl'Jl£e£l& . 











PUTU updates a record in the RECRD file. HEREIS 
receives control if the key from the file is invalid. 



DELR - Delete Record 

The DELR macro deletes a record from an indexed file. 
The indexing information is deleted from the file's 
associated index blocks (and directory blocks if 
necessary), and the data record is left unchanged. Proc- 
essing requirements differ depending upon access. 

Sequential access requires that the key value contained 
in KEYADR of the DEFIF macro be equal to the key 
value of the record obtained on the previous GET. If 
it is not equal, control goes to the invalid key routine. 

Random access does not require a preceding GET. If a 
record having the key value contained in KEYADR does 
not exist, control goes to the invalid key routine. The 
format for DELR is as follows: 



Name Operation 
[tag] DELR 



Operand 

IDENT=name 
KEYERR=symbolic address 



IDENT=name 

Specifies the file identifier. 

KEYERR=symbolic address 

Specifies the address which will receive control when a 
key error occurs. 



RECADR=symbolic address 



(Optional) 



Specifies the address of a record area. When R EC ADR is 
present in the PUTU macro, it overrides RECADR 
specified in a DEFIF macro. 



HE*} 



(Optional) 



If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
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If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 



Example 



„»« 




OPERATION 




OPERAND 


1 2 1 4 5 6 ? B 


9 


10 11 12 13 14 15 16 17 


18 


19 20 21 22 23 24 25 26 27 23 29 35 31 32 33 31 35 3fl 37 38 33 10 41 1J 43 44 15.46 


T!iP£ ._ _ 




CoASOLC 




o flr.su. Fi.'iAee,LA,i 

bA.r.flll.F.Z.s,UU3£7..S. . . .... , 











Example 



NAME 


OFEAATION 


OPIHAND 




ID 11 12 13 14 IS 16 ti 


8 19 20 21 23 n 2* 25 20 11 21 2S 30 31 32 33 3* 36 3fi 33 38 39 40. 41 42 43.44 45.88 




a«JJL^- IMHT.-miftD^K&fiM^tigOMfi 


* H" 







DELR deletes a given record from the indexed file RECRD. 
WRONG is the routine that handles key errors. 



The message located in the message area, LABELA, is 
transmitted to the console. When it is received, the 
reply is stored in the reply area, LABELB. 



MESSAGE - SET UP MESSAGE FORMAT 



CONSOLE COMMUNICATION MACROS 

Two macros, CONSOLE (an active macro) and MESSAGE 
(a data macro), are available for communicating with 
the operator's console. 

CONSOLE - TRANSMIT MESSAGE TO CONSOLE AND 
OPTIONALLY RECEIVE REPLY 

The CONSOLE macro enables programs to transmit 
messages to the operator's console and optionally re- 
ceive replies. The main-storage format of the message 
to be sent to the console must include two fields, a 
control block which is not typed and the text field 
which contains the actual message. The buffer set up 
to receive a reply from the console (if any) must contain 
a control block followed by the actual buffer for the 
reply text. The format of CONSOLE is as follows: 



Name Operation 



[tag] 



CONSOLE 



Operan d 

DATBUF1 symbolic address 
[DATBUF2=symbolic address] 



DATBUF1=symbolic address 

Specifies the address of the message control block which 
is followed by the message text. 



DATBUF2=symbolic address 



(Optional) 



Specifies the address of the reply control block which is 
followed by the reply buffer area. 



The MESSAGE macro, to be used in conjunction with 
the CONSOLE macro, simplifies the generation of messages 
by creating the correct format required by CONSOLE. 
A tag is required for all MESSAGE macros so that the 
corresponding CONSOLE macro may locate it. Two for- 
mats exist for the MESSAGE macro, one for generating 
an output message and one for generating a reply buffer. 



Generation of an Output Message 

The format for generating an output message is as 
follows: 



Name Operation 

tag 



Operand 



MESSAGE [DATBUF1=symbolic address] 

!DATSIZ1=decimal number 
DATATXT=character string 



DATBUF1=symbolic address 



(Optional) 



Enables a name to be attached to the beginning of the 
message text field. 



DATSIZ1=decimal number 

Specifies the decimal length (in bytes) of the message 
text. If no length is specified, the text length will be used. 
If there is no message, a length of zero is assumed. The 
maximum value of DATSIZ1 is 100. 
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DATATXT=character string 



DATSIZ2=decimal number 



Specifies the actual message to be placed in the message 
text field. It is created in EBCDIC and may be up to 100 
characters (bytes) long. The default is a string of blanks, 
with length being determined by the parameter DATSIZ1. 
The character string must be coded in the form, C'message 
text'. 



Specifies the decimal length in characters (bytes) of the 
reply buffer to be generated. The reply field will be 
assembled with blanks. The maximum value of DATSIZ2 
is 100. 

Example 



MODE; 



® 



(Optional) 



Specifies whether the message is informative (I) or 
directive (D). MODE=D indicates that the message calls 
for some operator action. The default value of MODE is I. 



„., 




OPERATION 




OPERAND 


I 2 3 1 5-6 1 H 


9 


III 11 12 1.1 14 16 1 Ft 17 


18 


IS 2D 21 22 23 24 25 26 27 28 29 30 31 3! 33 34 35 35 37 IS 33 40 41 42 43 44 45,46 


LASFLB. 




H.ES.SUM. 




M.T6llF,Z.e.i.A&£.Lb.,» . 

DATS.1 XI* ZD. . . 



Creates a reply area at assembly time consisting of a 
reply control block, LAB ELD, followed by a 20-byte 
reply text buffer, LAB ELD. 



Example 



„», 




„„„,„„ 




OF Efl AND 


12 3 4 5 6 7 8 


S 


10 11 12 13 14 IS 16 17 


18 


M9 20 21 22 23 24 25 26 27 28 23 30 31 (2 33 34 36 36 37 38 39 40 41 42 4.144 46.1G 


LX&EtX 




Me.s,s.a.s.£ 




DAT&dFt'L.fi6£,L.C. l : r . . . ■ 

fl.ft.TAIZ.lJ Z.O., ', 

bJLThTtT.A.' F.O.KnkT. S.HHO.S, 



Creates a message area at assembly time consisting of a 
message control block, LABELA, followed by a message 
text area, LABELC. The message text area will be 
20 bytes long. The first 12 bytes will contain FORMAT 
ERROR and the remaining eight bytes will contain 
blanks. 



CONTROL PROGRAM SERVICES MACROS 

Control Program Services macros are those macros which 
are implemented directly by the Control Program itself. 
These macros include: 

• Program Termination 



Generation of a Reply Buffer 

The format for generating a reply buffer is as follows: 



Name Operation 



Operand 



tag MESSAGE [DATBUF2=symbolic address] 

DATSIZ2=decimal number 



HALT 
EHALT 

ABEND 

Time and Date 

TIME 

SDATE 

JDATE 



PROGRAM TERMINATION MACROS 



DATBUF2=symbolic address 



(Optional) 



Enables a name to be attached to the beginning of the 
reply text field. 



Three macros are provided for program termination, 
HALT for normal step termination, EHALT for step and 
job termination, and ABEND for abnormal termination. 
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HALT — Terminate Program 



TIME — Retrieve Time of Day* 



The HALT macro is used to perform normal termination 
of a user's program step. This macro will not result in a 
memory dump unless DUMP=YES has been coded in the 
//EXECUTE statement associated with the program. The 
format for HALT is as follows: 



The TIME macro returns the current time of day in the 
operand specified. The time of day is returned in an 
unpacked decimal format: hhmmss, where hh is the 
hour, mm is the minute, and ss is the second. The format 
for TIME is as follows: 



Name 

[tag] 



Operation 
HALT 



Name Operation Operand 

[tag] TIME I NFOADR=symbolic address 



EHALT — Terminate Program 

The EHALT (error halt) macro is used to request 
termination of a user's job. This macro will not 
automatically give a memory dump unless DUMP=YES 
has been coded in the //EXECUTE statement associated 
with the program. The format for EHALT is as follows: 



Name 
[tag] 



Operation 
EHALT 



ABEND - Terminate Program Abnormally 



INFOADR=symbolic address 

Specifies the first byte address of the area which receives 
the time. 



Example 



1. 2. 3, 4, 1.6 T.I 



rme. 



10 11. 13, 13. 14 IS. II, 17 II 11.30. 31 32 33 24. 35. 21.37 31.31 M. 31. 33. 33 34 31 » 37. 31 » 40.41 42 43 44 4S.4B 



IMffl ADgjflL&aJt 



Transfers the current time (six bytes) to the memory lo- 
cation labeled CLOCK. 



The ABEND macro is used to request abnormal 
termination of a job, and to pass a completion code to 
Job Monitor for display. A dump will be given unless 
DUMP=NO is specified on the //EXECUTE statement. 
The completion code is a 16-bit binary value. The format 
for ABEND is as follows: 



Name Operation 
[tag] ABEND 

lNFOADR=symbolic address 



Operand 
INFOADR=symbolic address 



Specifies the first byte address of the area containing the 
completion code. 



SDATE - Retrieve System Date 

The SDATE (system date) macro returns the system date 
in the operand specified. The date is returned in one of 
two unpacked decimal formats: mmddyy or yyjjj, 
where mm is the month, dd is the day, yy is the year, 
and jjj is the Julian day. The format for SDATE is as 
follows: 



Name Operation 



Operand 



tag 



SDATE 



INFOADR=symbolic address 
MODE=j$ 

INFOADR=symbolic address 



TIME AND DATE MACROS 



Specifies the first byte address of the area that receives 
the date. 



The time and date of program execution may be obtained 
from the system with the TIME and SDATE macros. 
A third macro, JDATE, is available for obtaining a 
special user-specified job date. 



•Function is available on minimal system (16K storage), but 
returns zeros. 



6-17 



MODE= 



$ 



Specifies the current date in the calendar (C) 6-byte 
format mmddyy or the Julian (U) 5-byte format yyjjj. 
The default value is C. 



Example 



NAME 




WE NATION 




ONRANff 


1 2 3 4 i 6 7 t 


9 


ID 11 12 13 14 15 16 If 


IE ta 30 21 2! 23 24 25 20 27 23 M 30 31 32 33 34 35 36 IT 31 3S 40 41 42 43 M 45.46 






5DAT£ . _. 




I\MfOADK«mTXi,n<LD,E-.C. . __ 











Transfers the system date, in calendar format, to the 
memory location labeled DATE 11 . 



JDATE - Retrieve Job Date 

The JDATE (job date) macro returns the date provided 
for by a //SET statement. The date returned will be the 
system date unless the //SET statement has specified 
a job date. The date is returned in one of two unpacked 
decimal formats: mmddyy or yyjjj, where mm is the month, 
dd is the day, yy is the year, and jjj is the Julian day. 
The format for JDATE is as follows: 



Name Operation 
tag JDATE 



Operand 

INFOADR=symbolic address 
MODE=jJ[ 



INFOADR=symbolic address 

Specifies the first byte address of the area which re- 
ceives the date. 



MODE; 



i £ } 



Specifies the current date in the calendar (C) 6-byte 
format mmddyy or Julian (J) 5-bit format yyjjj. The 
default value is C. 

Example 



HARM 


OFMAItON 


0MRAMD 


1 2 ] 4 5 1 7 I 


10 11 12 13 11 16 '8 17 


1 19 20 21 22 23 24 IB 21 11 ?.i 21 30 31 32 33 34 35 38 V 38 3fl 40 41 42 43 44 45.41 




IDJLTJE. , 


r/jj p flAjQft»oA.Tj«,rtoajtiJt ^ . 







Transfers the job date, in Julian format, to the memory 
location labeled DATE2. 
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A. LIST PARAMETER 



The LIST parameter, which is used by the logical I/O 
level file control macros and the GET/PUT macros, 
allows for separate generation of the parameter packet 
and the subroutine linkage. 



All logical I/O level requests perform a subroutine call 
to either the GET/PUT module or the Data Management 
Open Close Control (DMOCC) using the following linkage 
conventions. 



1. Parameter list address set in general-purpose 
register 6 (R6) 



2. Save area address set in general-purpose 
register 7 (R7) 



\ 



LIST= 



JYES 
(NO 



The LIST parameter is used to generate parameter packets 
and subroutine linkages which make it possible to run 
program subroutines at execution time. The LIST=YES 
option generates the parameter packet, and the LIST=IMO 
option generates the subroutine linkage. (Tables A-1 
and A-2, at the end of this appendix, provide complete 
descriptions of the parameter packets for the GET/PUT 
and OPENL/CLOSEL macros.) 

When the LIST=NO option is specified, the IDENT 
parameter must be specified for the GET/PUT macros. 
Prior to issuing the LIST=NO option, the user must load 
R6 with the address of the appropriate parameter packet 
(generated by the LIST=YES option) to be used and must 
load R7 with the save area address. Together the address 
of the parameter packet and the subroutine linkage will 
take the program to the appropriate subroutine at 
execution time. When a program subroutine is used several 
times, the LIST=NO option provides ease and efficiency 
in coding. The subroutine linkage generated by LIST=NO 
has the coding format shown in Figure A-1 . 



LODD 



Return Address 



BDT Address (GET/PUT Macros) or DMOCC (OPENL/CLOSEL Macros) 




Figure A-1. Subroutine Linkage Coding Format 



A-1 



Example 



LIST DEFAULT 



3 « 5 6 3 8 



TA6.5. 

TAW. 

siMi x 



1! 12 13 14 IS IB 17 



L6MJL 

tlLT. . 



Pur. 
111 i. 6. 



19 ZO 31 11 li 1* ?B ?6 ll 28 39 3031 3? 33 3< 35 36 3f 31 39 40 Jl i2 fl3Ma5.1 



.S-toLCLItAl 

7J44.* 4 .«& . ■ 

LI.S.T*M6, J DStf.T.'.F /.<..£.& , . 

lAeti. T'.FXis.i., Xisr.'Ms. ".'.[ 



If the LIST option is omitted, subroutine linkage coding is 
generated followed by the appropriate parameter list. The 
user must load R7 with the save area address. Figure A-2 
shows the subroutine linkage coding format for the 
default of the LIST option. 



Subroutine 

Linkage 



PUT 

Parameter 

List 



Example 



.», 




OK RATION 




OMRAND 


1 Z 3 4 S fi 7 8 


9 


IP 11 12 13 H IS 16 17 


18 


19 JO 21 22 23 24 25 26 27 23 23 30 31 3! 33 31 35 36 37 38 39 40 41 42 43 44 iSW 


-— - 




JLOACl ^. 




sawc/t, (ti . .„._.... ._ 

1 bEUT* FILES , 












ikHEll^. 




tiJLH _ 




30. ... ^ ,..,..,.. . 





With the LODD instruction, the user loads the address of 
a parameter packet which has been specified elsewhere in 
the program (TAG4) and the address of the save area 
specified at SAVEIT. 

With the PUT macro and a LIST=NO parameter specified, 
a subroutine linkage is generated (IDENT must be 
specified). 

At address TAG4, the PUT parameter list is generated. 



Subroutine 

Linkage 

(Default) 



GET 

Parameter 

List 



The LIST default for the GET request results in the 
generation of the subroutine linkage and the GET param- 
eter list. 



LODD 



R7 



Return Address 



BSH 



BDT Address (GET/PUT Macros) or DMOCC (0PENL/CL0SEL Macros) 



Figure A-2. LIST Default Subroutine Linkage Coding Format 
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Table A-1. GET/PUT Parameter List 



10 
12 
14 
16 
18 
20 
22 



Length of List 


FC 


V/////////A 


1 


RA 


S 


R 


SL 


Error Code 


W////////////////////////////////////////////A 


STAG BDT 


BDT Address 


W///////////////////////////////////////////M 


STA6RSA 


Record Size Address 


«««§«««« 


STAGE A 


End Return Address 


Index External 


««««««« 


STAGRA 


Record Address 



Suffix * 
LL 

FC/BT 
ER 

BD 

SZ 

EA 



RA 



Bytes 


Bits 


Description 


0,1 




Length of parameter list. Always set to 4, 6, 8, 9, or 1 1 . 


2 




Function Codes (FC) 

GET 
11 PUT 

2 PUTU 

3 LOCRC 

7 DELR 

8 SETL 


3 


2 


Index external (1) \ 

Not indexed function 

1 Indexed function 




3 


Record address (RA) 

No record address 

1 Record address 




4 


Size parameter specified (S) 

No address specified in word 7 

1 Address of variable record size specified in word 7 




5 


Return parameter specified (R) 

No address specified in word 9 

1 Return address specified for EOF or invalid key in word 9 


3 


6,7 


SETL flag (SL) 

00 Positions to BOF 

01 Positions to record equal to KEYADR2 

1 Positions to record greater than or equal to KEYADR2 


4,5 




Error code, word contains the error code returned by the GET/PUT module if an 
error condition is detected. 


7 




Segment tag for BDT 


8,9 




BDT address (must be present) 



*The 2-character suffix for unique file identifier. 
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Table A-1. (Continued) 



Bytes 


Bits 


Description 


11 




Segment tag for record size address 


12,13 




Record size address. If S=1 (byte 3, bit 4), this address must be present This address 
points to a 2-byte location which contains the size (in binary) of the record. This 
parameter is required for PUT and PUTU and optional for GET. It is ignored for 
fixed length records. 


15 




Segment tag for end return address 


16,17 




End return address. If R-1 (byte 3, bit 5), this parameter must be present. This address 
is where control is returned if EOF, EOA, or an invalid key occurs. 


18,19 




Index external. If 1=1 (byte 3, bit 2), this is the external address of the functional 
module of indexed GET/PUT macros. 


21 




Segment tag for record address 


22,23 




Record address, an optional record area that can be specified in each GET or PUT 
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Table A-2. OPENL/CLOSEL Parameter List 






Length of List 


2 


FC 


cc 


» 


LK 


m 


u 


R 


LB 


4 


Error Code 


6 MmwMw/ 


W///////////////////A 


STAG BDT 


8 


BDT Address 


V/////////////////////j 

10 #/x^#//x/^z^/x^ 


wM^M^mw 


STAG LAB 


12 


Label Address 



Suffix* 
LL 

FC/BT 
ER 

BD 

LB 



Bytes 


Bits 


Description 


0,1 




Length of parameter list, always set to 6 


2 




Function codel(FC) 

4 OPENL(UsesCC, U, R, and LB) 

5 CLOSEL (Uses LK and R) 

6 CLOVE L (Uses none of these) 


3 





Control character (CC) 

ANSI control characters 

1 Device control characters 




2 


Lock(LK) 

No lock 

1 Lock 




4,5 


Usage (U) 

00 Input 

01 Input/output 
1 Output 


3 


6 


Rewind (R) 

No rewind 

1 Rewind 




7 


Label (LB) 

No label address specified in word 7 

1 Label address specified in word 7 


4,5 




Error code, word contains error code returned by the DMOCC module if an 
error condition is detected. 


7 




Segment tag for BDT 


8,9 




BDT address (must be present) 


11 




Segment tag for label address 


12,13 




Label address. If LB=1 (byte 3, bit 7), this is the address of the label packet. 



The 2-character suffix for unique file identifier. 
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B. LINKAGE CONVENTIONS 



Program linkage is the process of linking separately 
generated object modules into an execution unit. The 
following two basic functions must be performed in 
a linkage process: 

Matching of external address references 

Actual transfer of control during execution 



The first function is performed by a linkage editor, 
and it is not discussed in this manual. The second 
function is the linkage conventions established for the 
MRX/OS. 

The basic linkage conventions for a calling program 
include: 

1. Using the proper registers to establish linkage 

2. Reserving an area that is used by the called 
program to refer to the parameter list. 

3. Reserving an area in which the contents of 
the registers may be saved. 



REGISTER USE 

The linkage requires one or two registers, depending 
upon the passing of the address of the parameter list 
to the called program. 

The user must load the save area address into gen- 
eral-purpose register 7 (R7). 



If the parameter list is elsewhere in the program, the user 
loads the address of the parameter list into 
general -purpose register 6 (R6). 



PARAMETER LIST 

The parameter list is a list of contiguous words starting on 
a word boundary. It is the expansion of the macro call. 
When the parameter list is not found immediately after 
the macro call, the location of this parameter list must be 
loaded into R6. 



SAVE AREA 

The calling program must reserve an area of 22 bytes 
(beginning on an even-byte boundary) to be used by 
the called program for saving registers. The calling 
programs must load the address of the save area into 
R7. 

The following diagram illustrates the layout of the 
save area. 



Save-area 



+2 
+4 
+6 



Return Address 



Previous Save Area Address 



Status 



Contents of Register 



^ 



+20 



Contents of Register 7 
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THE CALLING SEQUENCE 



Out-of-Line 



The calling sequence has two forms, depending upon 
whether the return is in-line or out-of-line. 



In-Line 



«.. 


WERATION 


WEB AND 


1 2 3 4 i 6 7 B 


10 11 U 13 14 IS 16 1? 


< 13 Zfl 31 22 23 24 25 2f ?J 28 23 30 31 32 33 14 3B 36 37 38 38 4(1 4! 42 43 44 46.48 




i£JftJ>, ... . . 
«.S.« 


PAJLA±i£.r. t .Hb. .... efTjjOUAl^ . ^ _. 

tMJ,%.tt., , . . ..^... ,„ J ........_.^. 

S-CtAfttAe?, .. . ... .... ... _^- 


„._„._ 







12 1 4 5 B. 7. B 



). II. 12.13 14 16. IB. 17 



«0.6& 



19.20 21,22.23 24 2fi 2» .27 28 23 JO 31 3? 33 34 35 38.37 38 39 ,411.41.42 43 48 



PAH AC It 



OPT > on At. . . 






The parameter list address if elsewhere in the program, is 
loaded into R6. The address of the save area is loaded into 
R7. A branch and store register instruction saves the 
address of the next instruction in the return address of the 
save area. 



The parameter list address, if elsewhere in the program, is 
loaded into R6. The address of the save area is loaded into 
R7, The address of the user return (MYRTN) is loaded 
into the return address of the save area. Then a branch to 
the subroutine is performed. 
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C. PROGRAM FLOW 



The following figure illustrates the placement of the 
different macros in the program. 

The ID keyword of the Control Language //DEFINE 
statement and the IDENT keyword of OPENL/CLOSEL 
and GET/PUT correspond to the identifier entry of the 
define file macro. 



//DEF 
//DEF 


ID=FILE1 

ID=F1LE2 


FILE1 
FILE2 


DEFIF... 
DEFSF... 




OPENL IDENT=FILE1, 
OPENL IDENT=FILE2, 






V 






w 






GET IDENT=FILE2, 






JSwrnr'"^" 1 






1 ouu,ou UM ,, J 



PUT IDENT=FILE1, 



CLOSEL IDENT=FILE1, 
CLOSEL IDENT=FILE2, 



HALT 
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D. INDEX PORTION OF INDEXED FILE 



The following diagram (Figure D-1) gives the relationship 
of the different parts of the index portion of an indexed 
file. 



Block 1 
2 



Block n 
n+1 



Information Block 



Primary Index Blocks 



Available Space 



Directory to the Directory Block 



Directory Index Blocks 



Figure D-1, Index Portion of an Indaxed File Layout 



The layouts of the individual blocks are found in the 
succeeding sections of this appendix. 



INFORMATION BLOCK 

The Information Block of the Index portion of an 
indexed file gives the addresses of the last blocks of the 
data portion and index portion of the indexed file that 
were written. This enables Data Management to make 
further additions to the file. Figure D-2 gives the fields of 
the Information Block. 



Byte 
2 


Common Stored Data Record Header 


4 


Pass Boundary Index 


Track Boundary Index 


6 
8 


Block Address of Last Spattered Block Written 


10 


Available Space Block Address 


12 


Block Address of Directory to the Directory 


14 


Block Address of the Last Directory Index Block 


16 


Common Stored 1 
(1-3 bytes length) 


Data Space Header 


18 











Figure D-2. Information Block 
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DIRECTORY TO THE DIRECTORY BLOCK 

Figure D-3 gives the layout of the Directory to the 
Directory block. Each key value has an associated 
directory index block address. 



DIRECTORY INDEX BLOCK 

Figure D-4 gives the layout of the Directory Index block. 
Each key value has an associated primary index block 
address. 



Byte 
2 
4 
6 
8 
10 



m 
m+2 



n 
n+2 



Record Header 



Previous Block Link* 



Next Block Link* 



Count of Values in Block 



Key Value 1 
(1-100 Character EBCDIC) 



Pointer to Directory Index Block 



Key Value 2 



Ss I Key 2 



Pointer to Directory Index Block 



Space Header 
and 

Available Space 



Key 1 



Figure D-3. Directory to the Directory Block 



Byte 
2 
4 
6 
8 
10 



m+2 



n 
n+2 



Record Header 



Previous Block Link* 



Next Block Link* 



Count of Values in Block 



Key Value 1 
(1-100 Character EBCDIC) 



Pointer to Primary Index Block 



Key Value 2 



Pointer to Primary Index Block 



Space Header 

and 

Available Space 



Key 1 



key 2 



Figure D-4. Directory Index Block 



'The previous block link and next block link entries are not used in the directory blocks; they are reserved for 
future use. 



D-2 



PRIMARY INDEX BLOCK 

Figure D-5 gives the layout of the Primary Index block. 
Each key value has an associated block record address. 



Byte 
2 



8 
10 



m 
m+2 
m+4 



n 
n+2 
n+4 



Record Header 



Previous Block Link 



Next Block Link 



Count of Values in Block 



Key Value 1 
(1-100 Charactor EBCDIC 



Logical Block Number 



Record Number 



Key Value 2 



Logical Block Number 



Record Number 



Space Header 

and 

Available Space 



Key 1 



.Key 2 



Figure D-5. Primary Index Block 
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GLOSSARY 



Access 

Block 

Block I/O level 

Buffer switching 
Catalog 



Process of obtaining information from or placing information into storage. 

A set of words, characters, or records that are recorded as a unit. 

A processing level recognizing no logical records. Data is read or written as a physical 
data block. Further processing of logical records is a user responsibility. 

The transfer of processing from one buffer to another when two buffers are specified. 

Ordered compilation of item descriptions and sufficient information to give access to 
those items. 



Close 



Control Language 
statement 

Directive 



Debug 

Dump 

File 

File identifier 

File name 



Global register 
save area 



A function that makes a file unavailable for further processing and does label 
processing for end of file. 

A statement in a job that is used in identifying the job'or describing its requirements to 
the operating system. 

A control statement (as opposed to data) supplied to a program for the purpose of 
directing its mode of operation. 

The detection, location, and removal of mistakes from a routine or malfunctions from 
a computer. 

Copying of contents from internal storage to an external storage. 

A collection of related records treated as a unit. 

Identification given by the DEFSF, DEFRF, or DEFIF macro and referenced as the 
IDENT parameter of the GET/PUT and OPEN/CLOSE macros. IDENT is synonymous 
with the IDENTIFIER (ID) keyword of the Control Language //DEFINE statement. 

Cataloged name of file given by the FILENAME (FIL) keyword of the Control 
Language //DEFINE statement. This corresponds to the FILENAM parameter of the 
DEFLB macro. 

Storage area used for saving and restoring user registers that can be used by several 
routines. 



Information 
retrieval 

Job 

Job step 



Method and procedure of recovering specific information from stored data. 



A specified group of logically related tasks prescribed as a unit of work for a computer. 

The execution of a computer program explicitly identified by a Control Language 
statement. A job may specify that several job steps be executed. 
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Key Characters within a data item that are used to identify it or control its use. 

Label Symbols identifying or describing an item, record, message, or file. 

Load point Preset point (reflector strip) at which magnetic tape is initially positioned under the 

read/write head to start processing. 

Logical I/O level A processing level that reads and writes logical records. Data Management does the 
blocking and deblocking. 

Macro, action Macro which generates executable code that results in some action being taken at 

execution time. Such a macro is always coded in line with the executable part of the 
program. 

Macro, data Macro which generates nonexecutable code, such as an I/O control table, and should 

usually be coded in a data area of the program where an attempt to execute it (by 
mistake) is unlikely. Some macros are inherently data macros in any form while any 
system macro may become a data macro by including the parameter LIST=YES. 

Macro, system Instructions through which the user avails himself of the various system services, such 

as I/O processing. They form an extension to the standard machine instruction set and 
result in the generation of code which provides an interface with the system. 

Modification Code that restricts access to a file for security purposes, 

security code 

Open Function making file available for processing by checking label and file attributes. 

Packing Contiguous placement of records with no space in between records in a buffer. 

Physical I/O level The lowest level of I/O implementation available to the user. The user may have more 
responsibility for details, but gains in flexibility. This level of coding is independent of 
the system file organizations. 

Record Group of related items of data that are treated as a unit. 

Record identifier Identification of a record in terms of block number and relative position within that 
block. 

Relative record Number of a record relative to the beginning of the file, 
number 

Split cylinder Denotes the sharing of a cylinder by two files. 

Tag Character(s) attached to record or item for identification. 

Tape mark (TM) Special character written on magnetic tape signaling the physical end of the recording 
on tape. 

Thread An address pointing to the previous or next item in a series of logically related items. 

Unblocked record Block that contains only one record. 
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INDEX 



ABEND Macro 
Access 

random 

sequential 
ACCESS parameter 
Action macro 

BDT 

BINARY parameter 

BLKFAC parameter 

BLKSIZ parameter 

Block 

Block I/O level 

BREAK 

Buffer description table 

Buffer sharing 

Buffer switching 

BUFSHR parameter 

Bypass tape labels 

Catalog 

Central 

disc storage 

pack 
Central catalog 
CHECKOUT 
Close 

Close logical file 
Close tape file 
CLOSEL macro 
CLOVE L macro 
Common stored data format 
Conditional requests 
Console communication 

messages to 

replies from 
Console communication 
macros 

CONSOLE 

MESSAGE 
CONSOLE macro 
Control characters 
Control language 
CONTROL parameter 
Control program macros 

ABEND 

EHALT 

HALT 

JDATE 

SDATE 

TIME 
Control program services 



6-16,17 

2-1 ;3-1 ;6-3,5;Glossary-1 

2-1, 4,7;3-1, 3,4,8,9 

2-l,4,7;3-1,2,3,6,8,9 

2-4;6-3,4,5,8 

Glossary-2 

6-1 

6-2,8 

6-2,3,4,5,8 

6-2,3,4,5,8 

2-2;Glossary-1 

3-1;Glossary-1 

5-2 

6-1 

3-3;6-2,4,6 

3-3,5;Glossary-1 

6-2,3,4,5,6,8 

3-11,12 

2-8;Glossary-1 

2-10 

2-10 

2-10 

2-10 

1-1;5-1,2,4 

Glossary-1 

6-9 

3-12 

3-3,12;6-1,9 

3I2,13;6-1,10 

2-1 

5-4,5 

4-1 

4-2 

4-2 

6-15 

6-15 

6-15 

4-1 ,2,6-15 

2-3 

3-l3;Glossary-1 

2-3;6-8,9 

6-16 

6-16,17 

6-16,17 

6-16,17 

6-16,17 

6-16,17 

6-16,17 

1-1;4-1 



Data format 

Data macro 

Data Management 

Data Management macros 

CLOSEL 

CLOVEL 

DEFIF 

DEFLB 

DEFRF 

DEFSF 

DELR 

GET 

LOCRC 

OPENL 

PUT 

PUTU 

SETL 
Data portion of indexed files 
Data transmission macros 

DELR 

GET 

LOCRC 

PUT 

PUTU 

SETL 
DATATXT parameter 
DATBUF1 parameter 
DATBUF2 parameter 
DATSIZ1 parameter 
DATSIZ2 parameter 
Debugging 
DEFIF macro 
Define indexed file 
Define label 
Define relative file 
Define sequential file 
DEFLB macro 
DEFRF macro 
DEFSF macro 
Delete record 
DELR macro 
Device 

disc 

printer 

punch 

tape 

unit record 
Device usage 
Directive 
Directory index 
Directory to the directory 
index 



2-1 

Glossary-2 

1-1;3-13 

6-1 

6-1,9 

6-1,10 

6-1,5 

6-1,7 

6-1,3 

6-1,2 

6-1,14 

6-1,10 

6-1,13 

6-1,8 

6-1,12 

6-1,14 

6-1,12 

2-4 

6-1,10 

6-1,14 

6-1,10 

6-1,13 

6-1,12 

6-1,14 

6-1,12 

6-15,16 

6-2,3,4,5,6,8,15 

6-2,3,4,5,6,8,15,16 

6-15 

6-16 

1-1;5-2;Glossary-1 

2-7;6-1,5 

6-5 

6-7 

6-3 

6-2 

3-13;6-1,7 

2-4;6-1,3 

3-8;6-1,2 

6-14 

6-1,14 

2-1 

2-1,2,4,7 

2-3 

2-3 

2-1,2,4 

2-1,2,4 

2-1 

Glossary-1 

2-6,7 ;D-2 

2-6,7; D-2 



lndex-1 



Disc 


2-1,2,4,7 


IBM tape processing 


3-12 


Disc label 


2-10 


IDENT parameter 


6-8,9,10,11,12,13,14 


Disc storage catalog 


2-10 


IDXSA parameter 


6-10,11,12 


Dump 


Glossary- 1 


Ignore tape labels 


3-11,12 






INDBUF parameter 


6-5,6,8 






Indexed file 


2-1.3,4,6,8 


EHALT macro 


4-1;6-16,17 


Index portion of indexed file 


2-7; D-1 


END parameter 


6-3,5,8 


INDSHR parameter 


6-5,6,8 


End-of-file label 


2-9 


INDSIZ parameter 


6-5,6,8 


End-of-volume label 


2-9 


INFOADR parameter 


6-17,18 


ERROPT parameter 


6-2,3,4,5,6,8 


Information block 


D-1 






Information retrieval 


Glossary-1 


FDT 


3-11,12,13 


INMAIN parameter 


2-7; 6-5,6,8 


File 


2-1 ;Glossary-1 


Input files 


3-12 


indexed 


2-1, 3,4,6,8,6-5 


I/O processing 


3-1 


organization 


2-1,3,4,8 


logical record 


3-3 


permanent 


2-3,7,8 


magnetic tape 


3-8 


relative 


2-1, 3,4,5,8; 6-3 


random 


3-8,9,10 


scratch 


2-3,7,8 


sequential processing with 




sequential 


2-1, 3,4,5,8; 6-2 


record area 


3-3,6 


temporary 


2-3,7,8 


sequential processing without 


type 


2-1,3,7,8 


record area 


3-8,9 


work 


2-3,7,8 






File and label definition 




JDATE macro 


4-1; 6-1 8 


macros 


6-1 


Job 


Glossary-1 


DEFIF 


6-1,5 


Job step 


Glossary-1 


DEFLB 


6-1,7 






DEFRF 


6-1,3 


Kay 


Glossary-2 


DEFSF 


6-1,2 


KEYADR parameter 


6-3,4,8,13,14 


File control macros 


6-1,8 


KEYADR1 parameter 


6-5,6,8 


CLOSEL 


6-1,9 


KEYADR2 parameter 


6-5,6,8 


CLOVEL 


6-1,10 


KEYERR parameter 


6-12,14 


OPENL 


6-1,8 


KEYSIZ parameter 


6-5,6,8 


File description table 


3-11,12,13 






File name 


Glossary-1 


LABDEF parameter 


6-8,9 


File organization 


2-1,4,8 


Label 


2-8;Glossary-1 


indexed 


2-1,3,4,6,8 


disc 


2-10 


relative 


2-1,3,4,5,8 


end-of-file 


2-9 


sequential 


2-1,3,4,5,8 


end-6f -volume 


2-9 


File sharing 


3-3 


header 


2-9 


File type 


2-1,3,7,8 


standard tape file 


2-9,1 0;6-2 


permanent 


2-3,7,8 


standard tape volume 


2-9 


scratch 


2-3,7,8 


tape 


2-8; 6-2 


temporary 


2-3,7,8 


LABEL parameter 


3-8 


work 


2-3,7,8 


Labeled tapes 


2-8;3-8,11,12 


File with standard label 


3-12 


LABTYP parameter 


3-8; 6-2,8 


FILENAM parameter 


6-7 


Linkage conventions 


B-1 


Fixed length record 


2-1, 3; 6-3,5 


LIST parameter 


6-8,9,10,1 1,1 2,1 3,14;A-1 


Forward key 


6-8 


Load point 


Glossary-2 






Locate record 


6-13 


GET macro 


3-3,8; 6-1, 10 


LOCRC macro 


6-1,13 


Get record 


6-10 


Logical I/O level 


3-1 ;Glossary-1 


Global register save area 


Glossary-1 


Logical record 


2-2 






Logical record processing 


3-3;Glossary-1 


HALT macro 


4-1;6-16,17 






Header label 


2-9 
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Macro expansions 
Macros 

ABEND 

CLOSEL 

CLOVEL 

CONSOLE 

console communication 

control program 

data management 

data transmission 

DEFIF 

DEFLB 

DEFRF 

DEFSF 

DELR 

EHALT 

file and label definition 

file control 

GET 

HALT 

JDATE 

LOCRC 

MESSAGE 

OPENL 

PUT 

PUTU 

SDATE 

SETL 

TIME 
Magnetic tape processing 

bypass tape labels 

close tape file 

ignore tape labels 

open tape file 
MESSAGE macro 
Message to console 
MODE parameter 
Modification security code 
MSC parameter 

Nonstandard labels 

Open 

Open logical file 
Open tape file 
OPENL macro 
Output files 
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6-16,17 
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6-16 

6-1 

6-1,10 

2-7; 6-1, 5 
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2-4; 6-1, 3 

3-8; 6- 1,2 

6-1,14 

4-1; ; 6-16,17 

6-1 

6-1,8 
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4-1;6-16,17 

4-1; 6-1 8 

6-1,13 

4-1, 2; 6-1 5,1 6 

2-3,4,7,8:3-3,1 1,13;6-1, 8 

3-3,8 ;6-1, 12 

6-1,14 

4-1;6-16,17 

3-1;6-1,12 

4-1;6-16,17 

3-8 

3-11,12 

3-12 

3-11,12 

3-11 

4-1,2;6-15,16 

4-2 

6-15,16,17,18 

Glossary-2 

6-7 

2-8;3-8,11,12 

Glossary-2 

6-8 

3-11 

2-3,4,7,8;3-3,1 1,1 3;6-1,8 

3-12 



Pack catalog 
Packing 



2-10 
Glossary-2 



Parameters 

ACCESS 

BINARY 

BLKFAC 

BLKSIZ 

BUFSHR 

CONTROL 

DATATXT 

DATBUF1 

DATBUF2 

DATSIZ1 

DATSIZ2 

END 

ERROPT 

FILENAM 

IDENT 

IDXSA 

INDBUF 

INDSHR 

INDSIZ 

INFO ADR 

INMAIN 

KEYADR 

KEYADR1 

KEYADR2 

KEYERR 

KEYSIZ 

LABDEF 

LABEL 

LABTYP 

LIST 

MODE 

MSC 

RECADR 

RECREG 

RECSIZ 

RECTYP 

REWIND 

RTNADR 

START 

USAGE 

VERIFY 
Permanent file 
Physical I/O level 
Primary index 
Printer 
PROG 

Program termination 
Punch 
PUT macro 
Put record 
Put update 
PUTU macro 



2-4:6-3,4,5,8 

6-2,8 

6-2,3,4,5,8 

6-2,3,4,5,8 

6-2,3,4,5,6,8 

2-3;6-8,9 

6-15,16 

6-2,3,4,5,6,8,15 

6-2,3,4,5,6,8,15,16 

6-15 

6-16 

6-3,5,8 

6-2,3,4,5,6,8 

6-7 

6-8,9,10,11,12,13,14 

6-10,11,12 

6-5,6,8 

6-5,6,8 

6-5,6,8 

6-17,18 

2-7; 6-5,6,8 

6-3,4,8,13,14 

6-5,6,8 

6-5,6,8 

6-12,14 

6-5,6,8 

6-8.9 

3-8 

3-8:6-2,8 

6-8,9,10,1 1,12,13,14;A-1 

6-15,16,17,18 

6-7 

6-2,3,4,5,7,8,10,11,12,14 

6-2,3,4,5,7.8 

6-2,3,5,7,8,10,11,12 

6-2,3,5,8 

6-8,9.10 

6-10,11,12 

6-3,5,8,12,13 

6-8,9 

6-2,3,5,7,8 

2-3,7,8 

3-1 

2-6,7; D-3 

2-3 

5-4 

4-1;6-16 

2-3 

3-3,8; 6-1, 12 

6-12 

6-14 

6-1,14 
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Random access 


2-1,4,7;3-1, 3,4,8,9;6-3,5 


Transmit message 


6-15 


RECADR parameter 


6-2,3,4,5,7,8,10,11,12,14 






Record 


2-1,2;Glossary-2 


Unblocked record 


Glossary-2 


Record headers 


2-2 


Unit record device 


2-1,2,4 


Record identifier 


Glossary-2 


Unlabeled tapes 


2-8:3-8,11,12 


Record size 


2-3:6-3,5,7 


Update record 


6-12,14 


Record type 


2-3:6-3,5 


Usage conflicts 


3-3 


fixed length 


2-1,3 


USAGE parameter 


6-8,9 


variable length 


2-1,3 






RECREG parameter 


6-2,3,4,5,7,8 


Variable length record 


2-1,3:6-3,5 


RECREG use 


6-7 


VERIFY parameter 


6-2,3,5,7,8 


RECSIZ parameter 


6-2,3,5,7,8,10,11,12 


Volume switching 


3-12;6-10 


RECTYP parameter 


6-2,3,5,8 






Relative file 


2-1,3,4,5,8:6-3 


Work file 


2-3,7,8 


Relative record number 


Glossary-2 






Replies from console 


4-2 






Retrieve job date 


6-18 






Retrieve system date 


6-17 






Retrieve time of day 


6-17 






REWIND parameter 


6-8,9,10 






RTNADR parameter 


6-10,11,12 






Save area 


B-1 






Scratch file 


2-3,7,8 






SDATE macro 


4-1;6-16,17 






Sequential access 


2-1 ,4,7; 3-1,2,3,6,8,9; 
6-3,5 






Sequential file 


2-1,3,4,5,8:6-2 






Sequential processing with 








record area 


3-3,6:6-3 






Sequential processing without 








record area 


3-7,8,9 






Set limits 


6-12 






Set up message format 


6-15 






SETL macro 


3-1:6-1,12 






Space headers 


2-2 






Split cylinder 


Glossary-2 






Standard tape file label 


2-9;6-2 






Standard tape volume label 


2-9 






START parameter 


6-3,5,8,12,13 






System macro 


Glossary-2 






Tag 


Glossary-2 






Tape 


2-1,2,4 






Tape label 


2-8:6-2 






Tape mark 


Glossary-2 






Tape organization 


2-9 






Labeled 


2-8:3-8,11,12 






nonstandard labels 


2-8:3-8,11,12 






Unlabeled 


2-8:3-8,11,12 






Temporary file 


2-3,7,8 






Terminate program abnormally 


6-17 






Terminate program normally 


6-17 






Thread 


Glossary-2 






Time and date retrieval 


4-1 






TIME macro 


4-1,6-16,17 
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